One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.
TypeScript byoccloud-storagecloudflare-r2encryptiongoogle-drivenextcloudoauth2pkcepythons3sdkstoragetypescriptwebdav
BYOC v0.2.1: universal storage abstraction for TypeScript and Python
Ajay Raminenifcbbf8d7a04f
diff --git a/.editorconfig b/.editorconfignew file mode 100644index 0000000..196ddc7--- /dev/null+++ b/.editorconfig@@ -0,0 +1,19 @@+# https://editorconfig.org+root = true++[*]+charset = utf-8+end_of_line = lf+insert_final_newline = true+trim_trailing_whitespace = true+indent_style = space+indent_size = 2++[*.{py,pyi}]+indent_size = 4++[*.md]+trim_trailing_whitespace = false++[Makefile]+indent_style = tabdiff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 0000000..ae23c47--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,64 @@+name: Bug report+description: Something behaves differently than documented.+labels: [bug]+body:+ - type: dropdown+ id: sdk+ attributes:+ label: SDK+ options:+ - TypeScript (@byoc/*)+ - Python (byoc-storage)+ - Both+ validations:+ required: true++ - type: dropdown+ id: provider+ attributes:+ label: Provider+ options:+ - Google Drive+ - S3-compatible (R2 / AWS S3 / MinIO / Wasabi)+ - WebDAV (Nextcloud / ownCloud / Synology)+ - Core, not provider-specific+ validations:+ required: true++ - type: input+ id: version+ attributes:+ label: Version+ placeholder: "@byoc/core 0.2.0, or byoc-storage 0.2.0"+ validations:+ required: true++ - type: textarea+ id: expected+ attributes:+ label: What was expected, and what happened instead+ validations:+ required: true++ - type: textarea+ id: reproduce+ attributes:+ label: Minimal reproduction+ description: >-+ The smallest code that shows the problem. If it involves a filename,+ include the exact characters: several past bugs were specific to `#`,+ `?`, or apostrophes in paths.+ render: shell++ - type: textarea+ id: error+ attributes:+ label: Error output+ description: Full message and stack trace. Redact tokens before pasting.+ render: shell++ - type: input+ id: env+ attributes:+ label: Environment+ placeholder: "Node 22.3 / Python 3.12, macOS 15"diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..f2fa648--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,8 @@+blank_issues_enabled: true+contact_links:+ - name: Security vulnerability+ url: https://github.com/Ajayvarmaramineni/BYOC/security/advisories/new+ about: Report privately. Please do not open a public issue.+ - name: Google Drive OAuth setup help+ url: https://github.com/Ajayvarmaramineni/BYOC/blob/main/docs/google-oauth-setup.md+ about: Most Drive setup problems are covered in the guide.diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlnew file mode 100644index 0000000..e7bb231--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -0,0 +1,27 @@+name: Feature request+description: Suggest a capability or a new provider adapter.+labels: [enhancement]+body:+ - type: textarea+ id: problem+ attributes:+ label: The problem+ description: What are you unable to do today?+ validations:+ required: true++ - type: textarea+ id: proposal+ attributes:+ label: Proposed solution++ - type: checkboxes+ id: scope+ attributes:+ label: Scope+ description: >-+ BYOC is a blob and file-storage abstraction, not a database layer.+ Provider-specific concepts belong inside adapters, never in core.+ options:+ - label: This fits the provider-neutral core, or belongs in an adapter+ - label: I would be willing to work on thisdiff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdnew file mode 100644index 0000000..c5f27cd--- /dev/null+++ b/.github/PULL_REQUEST_TEMPLATE.md@@ -0,0 +1,27 @@+## What changed++<!-- One or two sentences. Link the issue if there is one. -->++## Why++<!-- What problem does this solve? For a bug fix, what was the user-visible symptom? -->++## Checklist++- [ ] Tests pass in every affected SDK+ - TypeScript: `npm test && npm run typecheck`+ - Python: `pytest && mypy src && ruff check .`+- [ ] New behaviour has a test that fails without the change+- [ ] Provider-specific logic stays inside its adapter, not in core+- [ ] Public API changes are reflected in the relevant README++## Cross-SDK impact++<!-- Delete if not applicable. -->++- [ ] This touches a surface covered by `spec/fixtures` (paths, encoding, E2EE envelope, provider metadata)+- [ ] Both SDKs were updated together, and the interop suite passes++> Changing a conformance fixture is a breaking change: it can make previously+> written files unreadable. Bump the format version instead of editing a vector+> in place.diff --git a/.github/dependabot.yml b/.github/dependabot.ymlnew file mode 100644index 0000000..104f65d--- /dev/null+++ b/.github/dependabot.yml@@ -0,0 +1,27 @@+version: 2++updates:+ - package-ecosystem: npm+ directory: /+ schedule:+ interval: weekly+ open-pull-requests-limit: 5+ groups:+ # Group only minor and patch bumps. A major update belongs in its own+ # pull request, so a breaking change is not bundled with routine ones.+ dev-dependencies:+ dependency-type: development+ update-types:+ - minor+ - patch++ - package-ecosystem: pip+ directory: /python+ schedule:+ interval: weekly+ open-pull-requests-limit: 5++ - package-ecosystem: github-actions+ directory: /+ schedule:+ interval: monthlydiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlnew file mode 100644index 0000000..76cc89a--- /dev/null+++ b/.github/workflows/ci.yml@@ -0,0 +1,157 @@+name: CI++on:+ push:+ branches: [main]+ pull_request:+ branches: [main]++jobs:+ typescript:+ name: TypeScript (Node ${{ matrix.node-version }})+ runs-on: ubuntu-latest+ strategy:+ fail-fast: false+ matrix:+ node-version: [20.x, 22.x]++ steps:+ - name: Checkout repository+ uses: actions/checkout@v7++ - name: Setup Node.js ${{ matrix.node-version }}+ uses: actions/setup-node@v7+ with:+ node-version: ${{ matrix.node-version }}+ cache: "npm"++ - name: Install dependencies+ run: npm ci++ - name: Build all workspaces+ run: npm run build++ - name: Typecheck TypeScript packages+ run: npm run typecheck++ - name: Run unit and conformance suites+ run: npm test++ python:+ name: Python ${{ matrix.python-version }}+ runs-on: ubuntu-latest+ strategy:+ fail-fast: false+ matrix:+ python-version: ["3.10", "3.11", "3.12", "3.13"]++ defaults:+ run:+ working-directory: python++ steps:+ - name: Checkout repository+ uses: actions/checkout@v7++ - name: Setup Python ${{ matrix.python-version }}+ uses: actions/setup-python@v7+ with:+ python-version: ${{ matrix.python-version }}+ cache: "pip"++ - name: Install package and dev dependencies+ run: pip install -e ".[dev]"++ - name: Lint+ run: ruff check .++ - name: Typecheck (strict)+ run: mypy src++ - name: Run unit and conformance suites+ run: pytest -q++ integration:+ name: Live integration (MinIO + WebDAV)+ runs-on: ubuntu-latest++ env:+ BYOC_TEST_S3_ENDPOINT: http://127.0.0.1:9000+ BYOC_TEST_S3_ACCESS_KEY: minioadmin+ BYOC_TEST_S3_SECRET_KEY: minioadmin+ BYOC_TEST_S3_REGION: us-east-1+ BYOC_TEST_S3_BUCKET: byoc-integration++ steps:+ - name: Checkout repository+ uses: actions/checkout@v7++ - name: Setup Python+ uses: actions/setup-python@v7+ with:+ python-version: "3.12"+ cache: "pip"++ # The interop suite drives the TypeScript SDK from the Python test run,+ # so both SDKs act on the same live servers.+ - name: Setup Node.js+ uses: actions/setup-node@v7+ with:+ node-version: 22.x+ cache: "npm"++ - name: Build the TypeScript SDK+ run: |+ npm ci+ npm run build++ - name: Install package and dev dependencies+ working-directory: python+ run: pip install -e ".[dev]"++ # A real S3 implementation is the only thing that proves our signatures+ # are accepted; mocks cannot catch a SigV4 or key-encoding regression.+ # Run it with `docker run` rather than a `services:` block, because the+ # official image needs `server /data` as arguments and services cannot+ # pass them.+ - name: Start MinIO+ run: |+ docker run -d --name byoc-minio \+ -p 9000:9000 \+ -e MINIO_ROOT_USER=minioadmin \+ -e MINIO_ROOT_PASSWORD=minioadmin \+ minio/minio:latest server /data++ - name: Wait for MinIO+ run: |+ for i in $(seq 1 30); do+ if curl -sf http://127.0.0.1:9000/minio/health/live; then+ echo "MinIO is up"; exit 0+ fi+ sleep 2+ done+ echo "MinIO did not become healthy in time"+ docker logs byoc-minio || true+ exit 1++ - name: Run Python integration suite (MinIO + in-process WebDAV)+ working-directory: python+ run: pytest tests/integration -q -m integration++ - name: Run cross-SDK interop suite (TypeScript <-> Python)+ working-directory: python+ run: pytest tests/interop -q -m interop++ # Both suites skip themselves when a server is unreachable, which is right+ # locally and dangerous here: a broken service would look like a pass.+ - name: Fail if integration or interop tests self-skipped+ working-directory: python+ run: |+ for SUITE in integration interop; do+ OUT=$(pytest "tests/$SUITE" -q -m "$SUITE" 2>&1 | tail -3)+ echo "$SUITE: $OUT"+ if echo "$OUT" | grep -q "skipped"; then+ echo "::error::$SUITE suite self-skipped; a required server was unreachable."+ exit 1+ fi+ donediff --git a/.gitignore b/.gitignorenew file mode 100644index 0000000..4224537--- /dev/null+++ b/.gitignore@@ -0,0 +1,53 @@+# Node & Dependencies+node_modules/+.npm/++# Build Outputs & Type Information+dist/+*.tsbuildinfo++# Environment & Secrets+.env+.env.local+.env.*.local++# Python+__pycache__/+*.py[cod]+*.egg-info/+.venv/+venv/+build/+.Python++# Testing & Coverage+coverage/+.nyc_output/+.pytest_cache/+.mypy_cache/+.ruff_cache/+.tox/+htmlcov/+.coverage+.coverage.*++# Logs & Temp+*.log+npm-debug.log*+yarn-debug.log*+yarn-error.log*+.DS_Store++# IDE & Editors+.vscode/+.idea/+*.suo+*.ntvs*+*.njsproj+*.sln+*.sw?++# Local-only working folders+delete/+npm/+pypi/diff --git a/.nvmrc b/.nvmrcnew file mode 100644index 0000000..2bd5a0a--- /dev/null+++ b/.nvmrc@@ -0,0 +1 @@+22diff --git a/BYOC_logo.jpg b/BYOC_logo.jpgnew file mode 100644index 0000000..ba9096aBinary files /dev/null and b/BYOC_logo.jpg differdiff --git a/CHANGELOG.md b/CHANGELOG.mdnew file mode 100644index 0000000..7187e36--- /dev/null+++ b/CHANGELOG.md@@ -0,0 +1,109 @@+# Changelog++All notable changes to BYOC are documented here.++The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),+and this project follows [Semantic Versioning](https://semver.org/). While the+version is below `1.0.0`, the public API may change between minor releases.++---++## [0.2.1] - 2026-08-26++A packaging fix for the TypeScript SDK. No runtime behaviour changed, and the+Python SDK is unaffected, so `byoc-storage` stays at 0.2.0.++### Fixed++- **`@byoc/core` and `@byoc/google-drive` did not declare `@types/node`**, even+ though their published `.d.ts` files reference `Buffer` and `node:stream` in+ the public API. Consumers compiling with `skipLibCheck: false` saw+ `Cannot find name 'Buffer'` reported from inside the package. Both now depend+ on `@types/node`, so it resolves automatically.++### Changed++- All packages declare `homepage`, `bugs`, `engines` (Node >= 20), and `author`,+ so the npm pages link back to the repository and issue tracker+- Packages are marked `sideEffects: false`, letting bundlers tree-shake unused+ adapters++---++## [0.2.0] - 2026-08-26++The release that makes BYOC a two-language project, and the first one where every adapter has been run against a real server rather than a mock.++### Highlights++**Python SDK.** `byoc-storage` on PyPI (imported as `byoc`), with full adapter parity: Google Drive, S3-compatible, and WebDAV. It is idiomatic Python rather than a transliteration of the TypeScript: `snake_case`, real exception types you catch by class, `asyncio` throughout, dataclasses instead of a forced Pydantic dependency, and `mypy --strict` clean.++**Cross-SDK interop, proven automatically.** Both SDKs run against the same conformance vectors in [`spec/fixtures`](./spec), and an interop suite drives both against the same live servers on every push. A file written by a Next.js frontend is readable by a FastAPI backend, including client-side encrypted files: the AES-256-GCM envelope is byte-identical across both languages, at any valid iteration count.++**Live integration testing.** CI now runs against a real MinIO server and a real RFC 4918 WebDAV server, and fails the build if either suite silently self-skips. Google Drive cannot run in CI, so it ships with a manual validation script that exercises the full OAuth flow, awkward filenames, multi-chunk resumable upload, quota, and delete.++**Every provider is live-verified.** All four move off Beta.++### Added++- `byoc-storage` Python SDK: client, path handling, E2EE, retry, and all three provider adapters+- `spec/fixtures`: language-neutral conformance vectors for path normalization, RFC 3986 encoding, the E2EE envelope, provider metadata, AWS SigV4, and PKCE+- Cross-SDK interop suite covering storage round-trips, listings, encryption, and path handling in both directions+- Live integration suites for S3 (MinIO) and WebDAV, which skip cleanly when no server is reachable+- `python/scripts/validate_gdrive_live.py` for manual Google Drive validation+- [Google Drive OAuth Setup guide](./docs/google-oauth-setup.md), covering the Cloud console's silent-failure spots+- `AsyncBYOC` client with multi-provider registry, runtime switching, capability gating, and migration+- `EncryptedFileTokenStorage` for persisting OAuth sessions encrypted at rest, with owner-only file permissions+- Presigned URL support in the S3 adapter+- `partial` migration status, distinguishing "copied, but source cleanup failed" from a real transfer failure++### Fixed++- **Object keys containing `#` or `?` were silently truncated**, so `draft#2.pdf` and `draft#3.pdf` both wrote to the key `draft`, and the second upload overwrote the first. Path segments are now RFC 3986 encoded in both the S3 and WebDAV adapters.+- **AWS SigV4 signatures were rejected when a caller passed a canonically-cased header.** `Content-Type` was signed with an empty value while the real value went on the wire. Header names are now normalized before both signing and sending.+- **SigV4 canonical query strings were unsorted and used `+` for spaces**, so any request with two or more query parameters failed. This also blocked paginated listing.+- **Google Drive queries did not escape `'` or `\`**, so any filename containing an apostrophe returned a 400, and a crafted path could inject query clauses.+- **`list()` returned an empty array** in the S3 and WebDAV adapters rather than listing anything.+- **S3 `list()` stopped at 1000 objects**, silently dropping everything past the first page. It now follows `NextContinuationToken`.+- **Migration double-counted a file** when source deletion failed, reporting it as both migrated and failed.+- **Control characters were not stripped from virtual paths**, contradicting the documented behavior in `SECURITY.md`.+- **Google Drive cache self-healing missed the common case.** A cached file ID that resolved but pointed at a deleted file surfaced as a raw 404; the retry now wraps the operation, not just the resolution.+- Published packages shipped `dist/tsconfig.tsbuildinfo` (33 kB of build cache containing local absolute paths) and carried no README or LICENSE.+- Packages declared `"module": "./dist/index.mjs"`, a file that was never emitted, breaking bundler resolution.++### Security++- **PBKDF2 iterations raised from 100,000 to 600,000**, and key derivation moved off the event loop.+- **The E2EE envelope now records its own iteration count**, so raising the work factor no longer orphans previously encrypted files. Bumped to `BYOC_E2EE_V2`; V1 envelopes remain readable.+- **The iteration count is range-checked before key derivation.** It is read from untrusted storage and consumed before the GCM tag can authenticate it, so a 4-byte edit could otherwise force minutes of PBKDF2 per file. Accepted range is 10,000 to 2,000,000.+- **The magic header, iteration count, and salt are bound as GCM additional authenticated data**, so the envelope header cannot be edited undetected.+- Refresh tokens are persisted encrypted, in files created with `0600` before any bytes are written.+- `revoke()` clears local token storage even if the remote call fails.+- All development dependencies updated; `npm audit` reports zero vulnerabilities.++### Changed++- Google Drive, S3-compatible, WebDAV, and the Provider SDK are no longer marked Beta+- WebDAV `metadata()` in Python uses `PROPFIND` at `Depth: 0` rather than `HEAD`, which returns richer data uniformly and avoids a keep-alive desync some servers trigger by attaching a body to a `HEAD` 404+- `S3CompatibleProvider` no longer leaks `root_prefix` into a returned `StorageObject.path`, so returned paths can be fed straight back into the client+- CI runs a Node 20/22 matrix, a Python 3.10 through 3.13 matrix, and a live integration job+- All package manifests declare `Apache-2.0`, a repository URL, and `publishConfig.access: public`++### Known limitations++- **E2EE buffers the whole payload**, so client-side encryption and multi-gigabyte resumable uploads are currently mutually exclusive. The wrapper reports `resumableUploads: false` rather than failing at upload time.+- **The Python SDK is async only.** A synchronous facade for Celery, Django, and scripts is planned.+- **Two instances of the same provider type cannot be registered on one client**, since the registry is keyed by manifest id. This blocks migrating between two buckets on the same provider.+- **Google Drive is not covered by CI**, as it needs a real account and a browser consent step. Validate it with `python/scripts/validate_gdrive_live.py`.++---++## [0.1.0] - 2026-08-25++Initial release: the TypeScript storage abstraction, with Google Drive, S3-compatible, and WebDAV adapters, a stream-piped migration engine, client-side E2EE, and a provider certification SDK.++---++[0.2.1]: https://github.com/Ajayvarmaramineni/BYOC/releases/tag/v0.2.1+[0.2.0]: https://github.com/Ajayvarmaramineni/BYOC/releases/tag/v0.2.0+[0.1.0]: https://github.com/Ajayvarmaramineni/BYOC/releases/tag/v0.1.0diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.mdnew file mode 100644index 0000000..e7579f6--- /dev/null+++ b/CODE_OF_CONDUCT.md@@ -0,0 +1,53 @@+# Code of Conduct++## Our pledge++We as members, contributors, and maintainers pledge to make participation in+this project a harassment-free experience for everyone, regardless of age, body+size, visible or invisible disability, ethnicity, sex characteristics, gender+identity and expression, level of experience, education, socio-economic status,+nationality, personal appearance, race, caste, colour, religion, or sexual+identity and orientation.++## Our standards++Behaviour that contributes to a positive environment:++- Showing empathy and kindness toward other people+- Being respectful of differing opinions, viewpoints, and experiences+- Giving and gracefully accepting constructive feedback+- Accepting responsibility, apologising to those affected by our mistakes, and+ learning from the experience+- Focusing on what is best for the community, not just for ourselves++Unacceptable behaviour:++- Sexualised language or imagery, and sexual attention or advances of any kind+- Trolling, insulting or derogatory comments, and personal or political attacks+- Public or private harassment+- Publishing others' private information, such as a physical or email address,+ without their explicit permission+- Other conduct which could reasonably be considered inappropriate in a+ professional setting++## Enforcement++Instances of abusive, harassing, or otherwise unacceptable behaviour may be+reported to the maintainers at **[email protected]**. All complaints will be+reviewed and investigated promptly and fairly.++Maintainers are obligated to respect the privacy and security of the reporter of+any incident, and are responsible for clarifying and enforcing these standards.+They may remove, edit, or reject comments, commits, code, issues, and other+contributions that are not aligned with this Code of Conduct.++## Scope++This Code of Conduct applies within all community spaces, and also applies when+an individual is officially representing the project in public spaces.++## Attribution++Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),+version 2.1, available at+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..bca4ea4--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,173 @@+# Contributing to BYOC++Thanks for considering a contribution. BYOC is a monorepo containing two peer+SDKs that implement the same contract, so most changes touch both.++By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md).++---++## Repository layout++```text+packages/ TypeScript SDK, published to npm as @byoc/*+python/ Python SDK, published to PyPI as byoc-storage+spec/fixtures/ conformance vectors shared by both SDKs+docs/ setup and integration guides+examples/ runnable demonstrations+```++## Development setup++Both SDKs are developed independently. Node 20 or newer, Python 3.10 or newer.++### TypeScript++```bash+npm install+npm run build+npm test+npm run typecheck+```++### Python++```bash+cd python+python3 -m venv .venv+source .venv/bin/activate+pip install -e ".[dev]"++pytest+mypy src+ruff check .+```++Without activating the virtualenv, call the binaries directly: `.venv/bin/pytest`,+`.venv/bin/mypy src`, `.venv/bin/ruff check .`++## Running the full suite++```+TypeScript 193 tests npm test && npm run typecheck+Python 224 tests pytest && mypy src && ruff check .+```++Integration and interop tests skip automatically when no server is reachable, so+the default run stays offline. To exercise them locally, start a real S3 server:++```bash+brew install minio && minio server /tmp/byoc-minio-data --address :9000+```++The WebDAV suite starts its own in-process RFC 4918 server and needs no setup.+CI runs both against real servers on every push.++Google Drive cannot run in CI, since it needs a real account and a browser+consent step. If a change touches the Drive adapter, OAuth, or the path+resolver, validate it manually:++```bash+cd python && .venv/bin/python scripts/validate_gdrive_live.py+```++See the [Google Drive OAuth setup guide](./docs/google-oauth-setup.md) for the+one-time console configuration.++---++## The two rules that matter most++### 1. Core stays provider-neutral++> Google Drive is BYOC's first reference provider. Google Drive is not BYOC's+> architecture.++Provider-specific concepts, APIs, authentication mechanisms, proprietary+identifiers, and error quirks belong strictly inside adapters.++| Forbidden in core | Required in core |+| :--- | :--- |+| `driveFileId`, `s3ObjectKey`, `blobName` | `id`, `providerId` |+| `driveFolderId`, `s3Bucket`, `blobContainer` | `path`, `container` |+| `googleDriveAccessToken`, `awsAccessKey` | `Credential`, `AuthSession` |++### 2. The SDKs must not drift++Both SDKs run against the same vectors in [`spec/fixtures`](./spec). Those+fixtures cover the surfaces where independent implementations write to shared+external state:++| Fixture | Covers |+| :--- | :--- |+| `path-normalization.json` | which folder bytes land in |+| `path-encoding.json` | the actual object key or URL |+| `e2ee-envelope.json` | the encrypted envelope byte layout |+| `provider-metadata.json` | metadata key names written into provider storage |+| `sigv4.json` | AWS request signing |+| `pkce.json` | the OAuth challenge derivation |++**Changing an expectation in a fixture is a breaking change.** It can make+previously written files unreadable. Bump the format version, as+`BYOC_E2EE_V2` did, rather than editing a vector in place.++Everything else, including method names, error class hierarchies, and sync+versus async, is idiomatic per language and deliberately not specified. Python+uses `snake_case` and raises exceptions; TypeScript uses `camelCase` and throws.+Only the error *code* strings are shared.++---++## Adding a provider adapter++1. Create the package under `packages/` or a module under+ `python/src/byoc/providers/`.+2. Implement `BYOCProvider`.+3. Declare capabilities honestly. If a provider has no real folders, report+ `folders: false` and let `create_folder` raise `CapabilityUnsupportedError`.+ Do not fake a capability with prefix tricks.+4. Keep every provider-specific concept inside the adapter.+5. Verify with the certification suite:++```ts+import { runProviderComplianceSuite } from "@byoc/provider-sdk";+const report = await runProviderComplianceSuite(() => new MyProvider(config));+```++6. Add integration tests against a real server if one can run locally or in CI.++## Testing expectations++New behaviour needs a test that fails without the change.++Mocks prove what a request looks like; only a real server proves it is accepted.+Every serious bug in this project was invisible to mocked tests: object keys+containing `#` or `?` were silently truncated, SigV4 signatures were rejected+when a caller passed a canonically-cased header, and Drive queries broke on any+filename containing an apostrophe.++When fixing a bug of that kind, add the offending input to the shared fixtures+so neither SDK can regress.++## Pull requests++1. Branch from `main`.+2. Keep the change focused. Unrelated refactors make review harder.+3. Run the full suite in every affected SDK.+4. Update the relevant README if the public API changed.+5. Fill in the pull request template, including the cross-SDK section when the+ change touches a conformance surface.++Commit messages: a short imperative summary under 72 characters, with detail in+the body if the change needs explaining.++## Security++Do not open a public issue for a vulnerability. See the+[security policy](./SECURITY.md) for private reporting.++Never commit real credentials, and never use real user data in test fixtures.++## License++Contributions are licensed under the [Apache License 2.0](./LICENSE).diff --git a/LICENSE b/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/README.md b/README.mdnew file mode 100644index 0000000..b10ac0b--- /dev/null+++ b/README.md@@ -0,0 +1,354 @@+<div align="center">++<img src="./BYOC_logo.jpg" alt="BYOC Logo" width="320" style="border-radius: 28px; margin-bottom: 16px;" />++# BYOC: Bring Your Own Cloud++### One API. The user's own cloud.++<p>One storage API for Google Drive, Nextcloud, and S3-compatible clouds, so files live in accounts the end user already owns.</p>++[](https://github.com/Ajayvarmaramineni/BYOC/actions)+[](https://www.npmjs.com/package/@byoc/core)+[](https://pypi.org/project/byoc-storage/)+[](#testing-and-verification)+[](#testing-and-verification)+[](LICENSE)++</div>++---++## What is BYOC?++Every application that handles user files eventually pays the same tax: a storage bucket that grows forever, an egress bill that scales with success, and a compliance conversation about data nobody wanted to hold.++BYOC removes it. Rather than the application hosting every file, it reads and writes storage **the end user already owns**: a personal Google Drive, a company Nextcloud, an organization's own S3 bucket. One API, any supported backend, in TypeScript or Python.++```text+ YOUR APPLICATION+ │+ ┌──────────┴──────────┐+ │ BYOC │+ │ Universal Storage │+ └──────────┬──────────┘+ │+ ┌──────────────────────┼──────────────────────┐+ ▼ ▼ ▼+ PERSONAL CLOUD SELF-HOSTED DEVELOPER CLOUD+ Google Drive Nextcloud Cloudflare R2+ OneDrive (planned) ownCloud AWS S3+ Dropbox (planned) Synology NAS MinIO / Wasabi+```++The application talks to BYOC. BYOC handles OAuth and PKCE, token refresh, virtual path resolution, resumable chunked uploads, rate-limit retries, and the differences between providers.++---++## Install++BYOC ships two peer SDKs with the same capabilities. Pick your language, or use both.++<table>+<tr><th>TypeScript</th><th>Python</th></tr>+<tr valign="top">+<td>++```bash+npm install @byoc/core++npm install @byoc/google-drive+npm install @byoc/s3-compatible+npm install @byoc/webdav+```++</td>+<td>++```bash+pip install byoc-storage+```++All adapters are included.++</td>+</tr>+</table>++> The Python distribution is named `byoc-storage` because `byoc` on PyPI belongs to an unrelated project. The import name is still `byoc`.++---++## Quick start++<table>+<tr><th>TypeScript</th><th>Python</th></tr>+<tr valign="top">+<td>++```ts+import { BYOC } from "@byoc/core";+import { S3CompatibleProvider }+ from "@byoc/s3-compatible";++const storage = new BYOC({+ provider: new S3CompatibleProvider({+ endpoint: process.env.R2_ENDPOINT!,+ bucket: "user-assets",+ region: "auto",+ accessKeyId: process.env.R2_KEY!,+ secretAccessKey: process.env.R2_SECRET!+ })+});++await storage.connect();++await storage.writeText(+ "documents/welcome.md",+ "# Hello from BYOC!"+);++const text = await storage.readText(+ "documents/welcome.md"+);+```++</td>+<td>++```python+import os+from byoc import AsyncBYOC+from byoc.providers.s3 import (+ S3CompatibleProvider,+)++storage = AsyncBYOC(+ provider=S3CompatibleProvider(+ endpoint=os.environ["R2_ENDPOINT"],+ bucket="user-assets",+ region="auto",+ access_key_id=os.environ["R2_KEY"],+ secret_access_key=os.environ["R2_SECRET"],+ )+)++async with storage:+ await storage.write_text(+ "documents/welcome.md",+ "# Hello from BYOC!",+ )+ text = await storage.read_text(+ "documents/welcome.md"+ )+```++</td>+</tr>+</table>++The Python SDK is idiomatic Python, not a transliteration: `snake_case`, exceptions you catch by type, `asyncio` throughout, dataclasses rather than a forced Pydantic dependency.++**Google Drive** needs an OAuth client first. The [setup guide](./docs/google-oauth-setup.md) takes about 10 minutes and covers the three places the Google Cloud console fails silently.++---++## Supported providers++| Provider | Ownership model | TypeScript | Python | Status |+| :--- | :--- | :--- | :--- | :--- |+| **Google Drive** | Personal cloud | [`@byoc/google-drive`](./packages/google-drive) | `byoc.providers.gdrive` | Live-verified |+| **Cloudflare R2 / AWS S3 / MinIO / Wasabi** | Developer cloud | [`@byoc/s3-compatible`](./packages/s3-compatible) | `byoc.providers.s3` | Live-verified |+| **Nextcloud / ownCloud / WebDAV / Synology** | Self-hosted | [`@byoc/webdav`](./packages/webdav) | `byoc.providers.webdav` | Live-verified |+| **Provider Certification SDK** | Compliance harness | [`@byoc/provider-sdk`](./packages/provider-sdk) | planned | Stable |+| Microsoft OneDrive | Personal cloud | planned | planned | Planned |+| Dropbox | Personal cloud | planned | planned | Planned |++*Live-verified* means the adapter is exercised against a real server, not a mock. See [Testing and verification](#testing-and-verification).++---++## Cross-SDK compatibility++Both SDKs are peer implementations of one contract. They run against the same conformance vectors in [`spec/fixtures`](./spec), and an automated interop suite drives both against the same live servers on every push.++A file written by a Next.js frontend is readable by a FastAPI backend, and the reverse.++| Surface | Guarantee |+| :--- | :--- |+| Virtual paths | Identical normalization and RFC 3986 encoding |+| Object keys | `#`, `?`, spaces, apostrophes, and unicode round-trip in both |+| E2EE envelope | Byte-identical layout at any valid PBKDF2 iteration count |+| Provider metadata | `byocVirtualPath` stays camelCase in both languages |+| AWS SigV4 | Signatures match a clean-room reference implementation |+| PKCE | Verified against RFC 7636 Appendix B |++This matters because those surfaces write to **shared external state**. Everything else, including method names and error class hierarchies, is idiomatic per language and deliberately not specified.++---++## What BYOC is, and what it isn't++> **Use PostgreSQL for application data. Use the user's own cloud for their files.**++BYOC is a binary blob and file-storage abstraction. It is not a database replacement.++| Use PostgreSQL / SQLite / MySQL for | Use BYOC for |+| :--- | :--- |+| Users, logins, and sessions | Documents (PDF, DOCX, spreadsheets) |+| Relational data and foreign keys | Media (images, audio, 4K video) |+| ACID transactions and fast lookups | Large attachments and exports |+| Queries (`WHERE`, `JOIN`, `GROUP BY`) | Database backups (`.sql.gz`, `app.sqlite`) |++```text+FastAPI / Django / Next.js / Express+ │+ ├── PostgreSQL → users, subscriptions, permissions, metadata pointers+ │+ └── BYOC → the actual PDFs, photos, videos, model artifacts+ │+ ├── Google Drive (User A's personal storage)+ ├── Nextcloud (User B's self-hosted storage)+ └── Cloudflare R2 (User C's infrastructure bucket)+```++---++## Capabilities++**Storage**+- One API across personal clouds, self-hosted servers, and developer object storage+- Virtual POSIX paths (`users/123/report.pdf`) resolved to each provider's native addressing, including Google Drive's opaque file IDs+- Multi-provider registry with runtime switching, and stream-piped migration between any two providers+- Paginated listing that follows continuation tokens past provider page caps++**Uploads**+- Resumable chunked uploads with 256 KiB alignment, progress callbacks, and network-failure resumption+- Automatic MIME detection, with per-upload overrides+- Presigned URLs for S3-compatible backends, so a browser can fetch without proxying bytes through you++**Security**+- OAuth 2.0 with PKCE (RFC 7636) and CSRF state, using the non-restricted `drive.file` scope so you never enter Google's Restricted Scope assessment+- Client-side E2EE with AES-256-GCM and PBKDF2-HMAC-SHA256 at 600,000 iterations, with the work factor recorded in the envelope and range-checked before key derivation+- Encrypted-at-rest token storage, written with owner-only permissions+- Credential redaction in logs, covering bearer tokens, refresh tokens, and cloud access keys+- Path traversal rejection and control-character stripping on every virtual path++**Reliability**+- Exponential backoff with jitter, applied only to errors the provider marked retryable+- 404 self-healing: when a user renames or deletes a file outside the application, the stale cache entry is dropped and the path re-resolved+- Provider-neutral error taxonomy shared across both SDKs++---++## Testing and verification++```+TypeScript 193 tests tsc --strict+Python 224 tests mypy --strict, ruff+Interop 13 tests both SDKs, same live servers+```++Every adapter is exercised against a real server rather than a mock. Each of the following was a genuine bug caught that way and invisible to mocked tests:++- Object keys containing `#` or `?` were silently truncated, so `draft#2.pdf` and `draft#3.pdf` overwrote each other+- SigV4 signatures were rejected when a caller passed a canonically-cased header+- Google Drive queries broke on any filename containing an apostrophe++<table>+<tr><th>TypeScript</th><th>Python</th></tr>+<tr valign="top">+<td>++```bash+npm test+npm run typecheck+npm run build+```++</td>+<td>++```bash+cd python+pip install -e ".[dev]"+pytest+mypy src && ruff check .+```++</td>+</tr>+</table>++**Live integration.** Integration and interop suites skip automatically when no server is reachable, so the default run stays offline. To exercise them:++```bash+brew install minio && minio server /tmp/byoc-minio-data --address :9000+```++The WebDAV suite starts its own in-process RFC 4918 server and needs no setup. CI runs both against real servers on every push, and fails the build if either suite self-skips.++**Google Drive** cannot run in CI, since it requires a real account and a browser consent step. Validate it manually:++```bash+cd python && .venv/bin/python scripts/validate_gdrive_live.py+```++---++## Repository layout++```text+byoc/+├── packages/ # TypeScript SDK, published to npm+│ ├── core/ # universal client, paths, migration, E2EE, logging+│ ├── google-drive/ # OAuth PKCE, virtual paths, resumable uploads+│ ├── s3-compatible/ # SigV4 signer, R2 / S3 / MinIO client+│ ├── webdav/ # Nextcloud, ownCloud, Synology adapter+│ └── provider-sdk/ # certification harness for custom adapters+├── python/ # Python SDK, published to PyPI as byoc-storage+│ ├── src/byoc/ # client, paths, encryption, retry, providers/+│ ├── tests/ # unit, conformance, integration, interop+│ └── scripts/ # live Google Drive validation+├── spec/fixtures/ # cross-SDK conformance vectors+├── docs/ # setup and integration guides+└── examples/ # runnable demonstrations+ ├── node-quickstart/ # TypeScript+ └── python-quickstart/ # Python+```++---++## Provider isolation++> **Google Drive is BYOC's first reference provider. Google Drive is not BYOC's architecture.**++Core stays provider-neutral. Provider-specific concepts, APIs, authentication mechanisms, proprietary IDs, and error quirks belong strictly inside adapters.++| Forbidden in core | Required in core |+| :--- | :--- |+| `driveFileId`, `s3ObjectKey`, `blobName` | `id`, `providerId` |+| `driveFolderId`, `s3Bucket`, `blobContainer` | `path`, `container` |+| `googleDriveAccessToken`, `awsAccessKey` | `Credential`, `AuthSession` |++Building your own adapter? [`@byoc/provider-sdk`](./packages/provider-sdk) runs a certification suite against it.++---++## Documentation++| Guide | Contents |+| :--- | :--- |+| [Google Drive OAuth setup](./docs/google-oauth-setup.md) | Cloud console walkthrough, troubleshooting, token persistence |+| [Conformance fixtures](./spec) | The cross-SDK contract and how to run it |+| [Python SDK](./python) | Install, async client, FastAPI and Celery notes |+| [Changelog](./CHANGELOG.md) | Release history and known limitations |+| [Contributing](./CONTRIBUTING.md) | Development setup for both SDKs, and the pull request process |+| [Code of Conduct](./CODE_OF_CONDUCT.md) | Community standards and enforcement |+| [Security policy](./SECURITY.md) | Reporting vulnerabilities, security architecture |++---++## License++[Apache License 2.0](LICENSE). Free for personal, educational, and commercial use.diff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 0000000..bcb944f--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,138 @@+# Security Policy++BYOC connects applications to storage that other people own, and handles the+credentials that grant that access. Both SDKs are covered by this policy.++## Supported versions++| Version | Supported |+| :--- | :--- |+| 0.2.x | Yes |+| 0.1.x | No |++While the project is below `1.0.0`, only the latest minor release receives+security fixes.++## Reporting a vulnerability++**Please do not open a public issue.** Report privately through+[GitHub Private Vulnerability Reporting](https://github.com/Ajayvarmaramineni/BYOC/security/advisories/new),+or by email to **[email protected]**.++A useful report includes the affected SDK and version, the provider adapter if+it is specific to one, a minimal reproduction, and the impact you believe it+has. Expect an acknowledgement within 48 hours.++Please do not include real credentials in a report. A redacted reproduction is+always enough.++## Security architecture++### Minimal OAuth scope++The Google Drive adapter defaults to+`https://www.googleapis.com/auth/drive.file` and nothing else. That scope grants+access only to files the application created, or that the user explicitly opened+with it. It cannot read the rest of a user's Drive.++`drive.appdata` and `drive.file.readonly` are available via `GoogleDriveScope`+but are never requested unless a caller opts in. BYOC never requests the full+`drive` scope, which is what keeps applications out of Google's Restricted Scope+security assessment.++### PKCE and CSRF protection++All OAuth flows use PKCE (RFC 7636) with the `S256` challenge method, derived+from a cryptographically secure random verifier. Conformance is pinned by+`spec/fixtures/pkce.json`, whose first vector is RFC 7636 Appendix B.++A random `state` value is generated for CSRF protection. **Verifying it on the+callback is the caller's responsibility.** BYOC generates the value; it cannot+enforce that the application compares it.++### Client-side encryption++`EncryptedStorageWrapper` encrypts payloads before they reach any provider, so+the storage operator never sees plaintext.++- AES-256-GCM, with a key derived by PBKDF2-HMAC-SHA256+- 600,000 iterations by default, recorded in the envelope so raising the work+ factor does not orphan previously encrypted files+- The iteration count is read from untrusted storage and consumed before the GCM+ tag can authenticate it, so it is range-checked to 10,000..2,000,000 before+ any key derivation runs+- The magic header, iteration count, and salt are bound as GCM additional+ authenticated data, so the envelope header cannot be edited undetected+- Envelope layout is pinned by `spec/fixtures/e2ee-envelope.json` and is+ byte-identical across both SDKs++Payloads are buffered in memory, so E2EE does not currently compose with+resumable streaming uploads. The wrapper reports `resumableUploads: false`+rather than failing at upload time.++### Credential storage++The default token storage is in memory and is lost on restart.++For long-running services, `EncryptedFileTokenStorage` persists sessions+encrypted with the same AES-256-GCM envelope, in a file created with `0600`+permissions before any bytes are written. A refresh token is a long-lived+credential for the user's storage account: never write one in plaintext, and+never commit one.++`revoke()` clears local storage even when the remote revocation call fails, so a+revoked token cannot linger on disk.++### Credential redaction in logs++All logging passes through a redacting logger:++- TypeScript: `SafeLogger` in `packages/core/src/utils/logger.ts`+- Python: `SafeLogger` in `python/src/byoc/logging.py`++Bearer tokens, Google `ya29.` tokens, refresh tokens, client secrets, API keys,+and passwords are scrubbed by both value pattern and key name, recursively+through nested structures and exception traces, before anything reaches a+handler.++The default logger is silent, so importing BYOC never emits credentials by+accident.++### Path handling++Every virtual path is normalized before reaching a provider:++- TypeScript: `normalizeVirtualPath` in `packages/core/src/paths/resolver.ts`+- Python: `normalize_virtual_path` in `python/src/byoc/paths.py`++Directory traversal (`..`) is rejected with an error rather than silently+stripped. Control characters, including NUL, are removed. Path segments are+percent-encoded per RFC 3986 before they are used in a URL, so characters such+as `#` and `?` in a filename cannot truncate an object key.++### Query injection++The Google Drive adapter escapes `\` and `'` in every value interpolated into a+Drive API query, in that order. Without it, a filename containing an apostrophe+produces a malformed query, and a crafted path could inject additional query+clauses.++### Transport and retries++All provider traffic is HTTPS. Retries use exponential backoff with full jitter+and apply only to errors a provider marked retryable, so a permission failure is+never retried.++## Guidelines for contributors++1. Never commit real OAuth secrets, access tokens, or refresh tokens.+2. Never use real user data or credentials in test fixtures. The values in this+ repository, such as `AKIAIOSFODNN7EXAMPLE` and `minioadmin`, are published+ vendor examples and local test-server defaults.+3. Keep secrets in `.env`, which is git-ignored.+4. Any new value interpolated into a provider query or URL must be escaped or+ encoded for that provider's syntax.+5. Changing a conformance fixture can make previously written files unreadable.+ Bump the format version instead of editing a vector in place.+6. Run the full suite in every affected SDK before submitting:+ `npm test` and `pytest`, plus `mypy src` and `ruff check .` for Python.diff --git a/docs/google-oauth-setup.md b/docs/google-oauth-setup.mdnew file mode 100644index 0000000..c26ed7b--- /dev/null+++ b/docs/google-oauth-setup.md@@ -0,0 +1,221 @@+# Google Drive OAuth Setup++Everything you need to let BYOC read and write files in a user's Google Drive.++**Time:** about 10 minutes, once per Google Cloud project.++**You do not need Google verification.** BYOC uses the non-restricted `drive.file` scope, which grants access only to files your app created or that the user explicitly opened with it. Restricted scopes like full `drive` require a security assessment; `drive.file` does not. That is a deliberate design choice, and it is why this setup ends in ten minutes instead of six weeks.++The console UI is genuinely confusing in a few places. Each step below flags the exact spot where it goes wrong.++---++## 1. Create a project++[console.cloud.google.com](https://console.cloud.google.com) → project dropdown (top left) → **New Project**.++Name it anything (`byoc-dev` is fine). Wait for it to finish creating, then make sure it is the *selected* project before continuing.++## 2. Enable the Drive API++Search **"Google Drive API"** in the top bar → open it → **Enable**.++> ⚠️ **Easy to skip, and the failure is confusing.** Without this, OAuth succeeds and then every API call returns 403. If your token works but uploads fail, this is why.++## 3. Fill in Branding++**APIs & Services → OAuth consent screen** (newer consoles label this **Google Auth Platform → Branding**).++| Field | Value |+| :--- | :--- |+| App name | Anything, e.g. `BYOC-dev` |+| User support email | Your email |+| App logo | **Leave empty** |+| Application home page | **Leave empty** |+| Application privacy policy link | **Leave empty** |+| Application terms of service link | **Leave empty** |+| Authorized domains | **Leave empty** |+| **Developer contact information** | **Your email. Required.** |++Click **Save**.++> ⚠️ **Developer contact information sits at the very bottom of the page**, below all the optional fields. It is required, it is easy to miss, and until it is filled in the console shows *"Your app's OAuth configuration is incomplete"* and **silently refuses to save test users** on the next step. If step 4 appears to do nothing, come back here.++> ⚠️ **Do not upload a logo.** It does nothing for a private dev app and creates a verification obligation later.++> ⚠️ **Do not fill in the domain links.** Adding a home page or privacy policy URL makes Google require you to add and *verify ownership* of that domain under Authorized domains.++## 4. Add yourself as a test user++**Audience** in the left sidebar (older consoles: the *Test users* section of the consent screen).++Confirm **Publishing status** is `Testing`, then **+ Add users** → your email → **Add**.++**Verify it saved.** The counter above the table should change:++```+0 users (0 test, 0 other) / 100 user cap ← did not save+1 user (1 test, 0 other) / 100 user cap ← saved+```++If the table still says *"No rows to display"*, go back to step 3.++> ⚠️ **This must be the account you actually sign in with.** If you are signed into several Google accounts, the console may be showing you the project as one account while the OAuth flow picks a different one. Check the console URL: `authuser=3` means you have at least four accounts in that browser. The account named on any "Access blocked" screen is the one that needs to be in this list.++> ⚠️ **The "User support email" from step 3 is not a test user.** Your address appearing there grants nothing. Only this list does.++> ⚠️ Changes can take a few minutes to propagate. If you are certain the list is right and still get 403, wait five minutes and retry in a private window.++**Do not click "Publish app".** Publishing an unverified app is what triggers the review process you are avoiding.++## 5. Create the OAuth client++**Credentials → Create Credentials → OAuth client ID.**++**Application type** decides your redirect handling:++| Type | Use when | Redirect URIs |+| :--- | :--- | :--- |+| **Desktop app** | CLI tools, scripts, local dev | `http://localhost` pre-authorized, nothing to register |+| **Web application** | A real web app | You must register each URI exactly, e.g. `https://myapp.com/api/auth/callback` |++Copy the **Client ID** and **Client secret**.++> ⚠️ Picking "Web application" for a local script gives you `redirect_uri_mismatch`. For local development, choose Desktop app.++---++## Using it++### Public clients (browser, mobile, CLI)++Use PKCE and **no client secret**. A secret shipped in a browser bundle or a binary is not a secret.++```ts+import { BYOC } from "@byoc/core";+import {+ GoogleDriveProvider,+ GoogleDriveScope,+ generateCodeVerifier,+ generateCodeChallenge,+ generateOAuthState+} from "@byoc/google-drive";++const codeVerifier = generateCodeVerifier(64);+const codeChallenge = await generateCodeChallenge(codeVerifier);+const state = generateOAuthState(32);+// Store codeVerifier and state in the user's session.++const gdrive = new GoogleDriveProvider({+ auth: {+ clientId: process.env.GOOGLE_CLIENT_ID!,+ redirectUri: "https://myapp.com/api/auth/callback",+ scopes: [GoogleDriveScope.FILE]+ },+ rootFolderName: "MyApplication"+});++const loginUrl = gdrive.oauth.getAuthorizationUrl({ state, codeChallenge });+// Redirect the user to loginUrl.+```++On the callback, **compare the returned `state` to the stored one before doing anything else.** Skipping that check leaves the flow open to CSRF.++```ts+await gdrive.oauth.exchangeCode({ code, codeVerifier });++const storage = new BYOC({ provider: gdrive });+await storage.connect();+await storage.writeText("notes/meeting.md", "# Q3 Strategy Notes");+```++### Python++```python+from byoc import AsyncBYOC+from byoc.providers.gdrive import (+ GoogleDriveProvider,+ generate_code_challenge,+ generate_code_verifier,+ generate_oauth_state,+)++verifier = generate_code_verifier(64)+state = generate_oauth_state(32)++provider = GoogleDriveProvider(+ client_id=os.environ["GOOGLE_CLIENT_ID"],+ redirect_uri="https://myapp.com/api/auth/callback",+ root_folder_name="MyApplication",+)++login_url = provider.oauth.get_authorization_url(+ state=state, code_challenge=generate_code_challenge(verifier)+)+# ...redirect, then on the callback (after verifying state):+await provider.oauth.exchange_code(code=code, code_verifier=verifier)++storage = AsyncBYOC(provider=provider)+async with storage:+ await storage.write_text("notes/meeting.md", "# Q3 Strategy Notes")+```++### Keeping the session alive++BYOC requests `access_type=offline` and `prompt=consent` by default, which is what makes Google return a **refresh token**. Without both, the session dies in an hour and cannot be renewed.++The default token storage is in-memory, so sessions are lost on restart. For a long-running service, persist them encrypted:++```python+from byoc.providers.gdrive import EncryptedFileTokenStorage++provider = GoogleDriveProvider(+ client_id=os.environ["GOOGLE_CLIENT_ID"],+ token_storage=EncryptedFileTokenStorage(+ "./.byoc-session.enc", os.environ["TOKEN_ENCRYPTION_KEY"]+ ),+)+```++A refresh token is a long-lived credential for the user's Drive. Store it encrypted, never in plaintext, and never in source control.++---++## Verify it works++```bash+export BYOC_GDRIVE_CLIENT_ID="...apps.googleusercontent.com"+export BYOC_GDRIVE_CLIENT_SECRET="..."++cd python+.venv/bin/python scripts/validate_gdrive_live.py+```++> On macOS and most Linux distros there is no bare `python` on PATH, only+> `python3`. Calling the venv's interpreter directly, as above, works regardless+> and avoids needing to activate anything first.++This runs the full flow against your real Drive: OAuth, refresh token, uploads, awkward filenames, a multi-chunk resumable upload, quota, and delete. It cleans up the files it creates.++---++## Troubleshooting++| What you see | Cause | Fix |+| :--- | :--- | :--- |+| `Access blocked: ... has not completed the Google verification process`<br>`Error 403: access_denied` | The signed-in account is not a test user | Add **that exact address** (step 4). Check which account the error page names. |+| Test users will not save; *"OAuth configuration is incomplete"* | Developer contact information is empty | Fill it at the bottom of Branding (step 3) |+| `redirect_uri_mismatch` | Client is "Web application", or the URI is not registered exactly | Use Desktop app for local dev, or register the exact URI |+| OAuth succeeds, then every call is 403 | Drive API not enabled | Enable it (step 2) |+| No `refresh_token` in the response | Missing `access_type=offline` or `prompt=consent` | BYOC sets both by default; do not override them |+| `invalid_grant` on refresh | Refresh token revoked, expired, or the app is still in Testing | Re-run the consent flow. Testing-status refresh tokens expire after 7 days. |+| Works for you, fails for a teammate | They are not a test user | Add them, up to the 100-user cap |+| `Address already in use` on the validation script | An earlier run is still holding the port | `lsof -nP -iTCP:8765 -sTCP:LISTEN` then `kill <PID>` |++> ⚠️ **The 7-day refresh token expiry is worth planning around.** While your app is in `Testing`, Google expires refresh tokens after seven days, so users must re-consent weekly. That is fine for development. For production you either publish the app (verification is still not required for `drive.file`, but the consent screen review applies) or accept weekly re-auth.++---++## What your users see++Because the app is unverified, testers get an **"Google hasn't verified this app"** interstitial and must click *Advanced → Go to (app name)*. That is expected in `Testing` status and is different from the hard `access_denied` block, which means they are not on the test-user list at all.diff --git a/examples/node-quickstart/index.ts b/examples/node-quickstart/index.tsnew file mode 100644index 0000000..c682c0b--- /dev/null+++ b/examples/node-quickstart/index.ts@@ -0,0 +1,87 @@+import { BYOC } from "@byoc/core";+import {+ GoogleDriveProvider,+ GoogleDriveScope,+ generateCodeVerifier,+ generateCodeChallenge,+ generateOAuthState+} from "@byoc/google-drive";+import { S3CompatibleProvider } from "@byoc/s3-compatible";+import { WebDAVProvider } from "@byoc/webdav";++async function main() {+ console.log("=== BYOC (Bring Your Own Cloud) Ecosystem Demo ===\n");++ // 1. Generate PKCE Security Parameters+ const codeVerifier = generateCodeVerifier(64);+ const codeChallenge = await generateCodeChallenge(codeVerifier);+ const oauthState = generateOAuthState(32);++ console.log("1. PKCE Security Handshake:");+ console.log(" - Code Challenge:", codeChallenge);+ console.log(" - State:", oauthState);++ // 2. Initialize 3 Multi-Cloud Adapters+ // Personal Cloud: Google Drive+ const googleDrive = new GoogleDriveProvider({+ auth: {+ clientId: "demo-client-id.apps.googleusercontent.com",+ redirectUri: "http://localhost:3000/callback",+ scopes: [GoogleDriveScope.FILE],+ session: {+ accessToken: "mock-demo-access-token",+ expiresAt: Date.now() + 3600 * 1000+ }+ },+ rootFolderName: "MyDemoApp"+ });++ // Developer Cloud: Cloudflare R2 / AWS S3+ const cloudflareR2 = new S3CompatibleProvider({+ endpoint: "https://my-account-id.r2.cloudflarestorage.com",+ bucket: "user-backups",+ region: "auto",+ accessKeyId: "mock-r2-key",+ secretAccessKey: "mock-r2-secret",+ rootPrefix: "app-data"+ });++ // Self-Hosted / Privacy: Nextcloud / WebDAV+ const nextcloud = new WebDAVProvider({+ endpoint: "https://nextcloud.mycompany.com/remote.php/dav/files/user/",+ username: "john_doe",+ password: "app-password-123",+ rootFolder: "MyApp"+ });++ // 3. Initialize Universal BYOC Client with all 3 Clouds+ const storage = new BYOC({+ providers: [googleDrive, cloudflareR2, nextcloud],+ defaultProviderId: "google-drive"+ });++ console.log("\n2. Registered Storage Providers in BYOC Runtime:");+ for (const manifest of storage.getProviders()) {+ console.log(` - [${manifest.category.toUpperCase()}] ${manifest.name} (id: ${manifest.id}, auth: ${manifest.authentication})`);+ }++ // 4. Inspect Capabilities+ console.log("\n3. Active Provider Capabilities (" + storage.manifest().name + "):");+ console.log(" - Folders:", await storage.hasCapability("folders"));+ console.log(" - Quota:", await storage.hasCapability("quota"));+ console.log(" - Resumable Uploads:", await storage.hasCapability("resumableUploads"));++ // 5. Dynamic Switching Demonstration+ console.log("\n4. Dynamic Provider Switching:");+ storage.useProvider("s3-compatible");+ console.log(" Switched active provider to:", storage.manifest().name, `(${storage.manifest().category})`);++ storage.useProvider("webdav");+ console.log(" Switched active provider to:", storage.manifest().name, `(${storage.manifest().category})`);++ console.log("\n5. Ready to migrate data between user clouds and developer clouds with zero code changes!");+}++main().catch((err) => {+ console.error("BYOC Error:", err);+});diff --git a/examples/node-quickstart/package.json b/examples/node-quickstart/package.jsonnew file mode 100644index 0000000..b2d5c7b--- /dev/null+++ b/examples/node-quickstart/package.json@@ -0,0 +1,17 @@+{+ "name": "example-node-quickstart",+ "version": "0.2.1",+ "private": true,+ "description": "Quickstart example consuming @byoc/core and @byoc/google-drive",+ "main": "index.ts",+ "type": "module",+ "scripts": {+ "build": "tsc -b"+ },+ "dependencies": {+ "@byoc/core": "0.2.1",+ "@byoc/google-drive": "0.2.1",+ "@byoc/s3-compatible": "0.2.1",+ "@byoc/webdav": "0.2.1"+ }+}diff --git a/examples/node-quickstart/tsconfig.json b/examples/node-quickstart/tsconfig.jsonnew file mode 100644index 0000000..30eb516--- /dev/null+++ b/examples/node-quickstart/tsconfig.json@@ -0,0 +1,15 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": ".",+ "outDir": "dist",+ "noEmit": false+ },+ "references": [+ { "path": "../../packages/core" },+ { "path": "../../packages/google-drive" },+ { "path": "../../packages/s3-compatible" },+ { "path": "../../packages/webdav" }+ ],+ "include": ["index.ts"]+}diff --git a/examples/python-quickstart/README.md b/examples/python-quickstart/README.mdnew file mode 100644index 0000000..6b71c91--- /dev/null+++ b/examples/python-quickstart/README.md@@ -0,0 +1,24 @@+# Python quickstart++Mirrors [`../node-quickstart`](../node-quickstart), so the two SDKs can be+compared side by side.++```bash+pip install byoc-storage+python main.py+```++Runs offline by default. It registers all three providers, inspects their+capabilities, switches between them, and demonstrates client-side encryption+without contacting any server.++For a live round-trip, start a real S3 server first:++```bash+brew install minio+minio server /tmp/byoc-minio-data --address :9000+```++```bash+BYOC_DEMO_S3=1 python main.py+```diff --git a/examples/python-quickstart/main.py b/examples/python-quickstart/main.pynew file mode 100644index 0000000..a3b1c4f--- /dev/null+++ b/examples/python-quickstart/main.py@@ -0,0 +1,127 @@+#!/usr/bin/env python3+"""BYOC Python quickstart.++Mirrors examples/node-quickstart, so the two SDKs can be compared side by side.++Runs entirely offline by default: it registers all three providers, inspects+capabilities, switches between them, and demonstrates client-side encryption+without contacting any server.++Point it at a real S3 server to exercise a live round-trip::++ brew install minio+ minio server /tmp/byoc-minio-data --address :9000++ BYOC_DEMO_S3=1 python main.py+"""++from __future__ import annotations++import asyncio+import os++from byoc import AsyncBYOC, E2EECrypto+from byoc.providers.gdrive import (+ GoogleDriveProvider,+ generate_code_challenge,+ generate_code_verifier,+ generate_oauth_state,+)+from byoc.providers.s3 import S3CompatibleProvider+from byoc.providers.webdav import WebDAVProvider++S3_ENDPOINT = os.environ.get("BYOC_TEST_S3_ENDPOINT", "http://127.0.0.1:9000")+S3_BUCKET = os.environ.get("BYOC_TEST_S3_BUCKET", "byoc-integration")+++def build_providers() -> list[object]:+ """Construct one adapter per ownership model.++ Credentials are placeholders: nothing here contacts a provider until a+ storage call is actually made.+ """+ return [+ GoogleDriveProvider(+ client_id="your-client-id.apps.googleusercontent.com",+ redirect_uri="http://localhost:8765/callback",+ root_folder_name="MyApplication",+ ),+ S3CompatibleProvider(+ endpoint=S3_ENDPOINT,+ bucket=S3_BUCKET,+ region="auto",+ access_key_id=os.environ.get("BYOC_TEST_S3_ACCESS_KEY", "minioadmin"),+ secret_access_key=os.environ.get("BYOC_TEST_S3_SECRET_KEY", "minioadmin"),+ force_path_style=True,+ ),+ WebDAVProvider(+ endpoint="https://nextcloud.example.com/remote.php/dav/files/alex/",+ username="alex",+ password="an-app-password",+ ),+ ]+++async def main() -> None:+ print("=== BYOC (Bring Your Own Cloud) Python quickstart ===\n")++ # 1. PKCE, the handshake that protects the OAuth authorization code.+ verifier = generate_code_verifier(64)+ print("1. PKCE security handshake:")+ print(f" Code challenge: {generate_code_challenge(verifier)}")+ print(f" State: {generate_oauth_state(32)}\n")++ storage = AsyncBYOC(providers=build_providers(), default_provider_id="google-drive") # type: ignore[arg-type]++ # 2. One client, several ownership models.+ print("2. Registered storage providers:")+ for manifest in storage.get_providers():+ print(f" [{manifest.category.upper()}] {manifest.name} (id: {manifest.id})")+ print()++ # 3. Capabilities are declared, so callers feature-detect instead of guessing.+ print("3. Capabilities differ per provider, and BYOC reports them honestly:")+ for provider_id in ("google-drive", "s3-compatible", "webdav"):+ caps = storage.use_provider(provider_id).capabilities()+ print(+ f" {provider_id:16} folders={caps.folders!s:5} "+ f"quota={caps.quota!s:5} resumable={caps.resumable_uploads}"+ )+ print()++ # 4. Switching backends changes nothing about the calling code.+ print("4. Runtime provider switching:")+ for provider_id in ("s3-compatible", "webdav", "google-drive"):+ storage.use_provider(provider_id)+ print(f" active: {storage.manifest().name}")+ print()++ # 5. Client-side encryption, so the storage operator never sees plaintext.+ print("5. Client-side end-to-end encryption:")+ crypto = E2EECrypto(passphrase="correct-horse-battery-staple")+ envelope = await crypto.encrypt("Sensitive patient record")+ print(f" envelope: {bytes(envelope[:12]).decode()} + {len(envelope)} bytes total")+ print(f" plaintext: {(await crypto.decrypt(envelope)).decode()}")+ print(" The same envelope is readable by the TypeScript SDK.\n")++ # 6. Optional live round-trip against a real S3 server.+ if os.environ.get("BYOC_DEMO_S3"):+ print(f"6. Live round-trip against {S3_ENDPOINT}:")+ storage.use_provider("s3-compatible")+ await storage.connect()+ try:+ obj = await storage.write_text("quickstart/hello.md", "# Hello from BYOC!")+ print(f" wrote: {obj.path} ({obj.size} bytes)")+ print(f" read: {await storage.read_text('quickstart/hello.md')!r}")+ await storage.delete("quickstart/hello.md")+ print(f" exists after delete: {await storage.exists('quickstart/hello.md')}")+ finally:+ await storage.disconnect()+ else:+ print("6. Set BYOC_DEMO_S3=1 with a MinIO server running for a live round-trip.")++ print("\nReady to store files in storage the end user already owns.")+++if __name__ == "__main__":+ asyncio.run(main())diff --git a/package-lock.json b/package-lock.jsonnew file mode 100644index 0000000..14d050a--- /dev/null+++ b/package-lock.json@@ -0,0 +1,1774 @@+{+ "name": "byoc-monorepo",+ "version": "0.2.1",+ "lockfileVersion": 3,+ "requires": true,+ "packages": {+ "": {+ "name": "byoc-monorepo",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "workspaces": [+ "packages/*",+ "examples/*"+ ],+ "devDependencies": {+ "@types/node": "^20.14.0",+ "typescript": "^5.4.5",+ "vitest": "^3.0.0"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "examples/node-quickstart": {+ "name": "example-node-quickstart",+ "version": "0.2.1",+ "dependencies": {+ "@byoc/core": "0.2.1",+ "@byoc/google-drive": "0.2.1",+ "@byoc/s3-compatible": "0.2.1",+ "@byoc/webdav": "0.2.1"+ }+ },+ "node_modules/@byoc/core": {+ "resolved": "packages/core",+ "link": true+ },+ "node_modules/@byoc/google-drive": {+ "resolved": "packages/google-drive",+ "link": true+ },+ "node_modules/@byoc/provider-sdk": {+ "resolved": "packages/provider-sdk",+ "link": true+ },+ "node_modules/@byoc/s3-compatible": {+ "resolved": "packages/s3-compatible",+ "link": true+ },+ "node_modules/@byoc/webdav": {+ "resolved": "packages/webdav",+ "link": true+ },+ "node_modules/@esbuild/aix-ppc64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",+ "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",+ "cpu": [+ "ppc64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "aix"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/android-arm": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",+ "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",+ "cpu": [+ "arm"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "android"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/android-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",+ "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "android"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/android-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",+ "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "android"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/darwin-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",+ "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/darwin-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",+ "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/freebsd-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",+ "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "freebsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/freebsd-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",+ "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "freebsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-arm": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",+ "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",+ "cpu": [+ "arm"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",+ "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-ia32": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",+ "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",+ "cpu": [+ "ia32"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-loong64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",+ "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",+ "cpu": [+ "loong64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-mips64el": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",+ "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",+ "cpu": [+ "mips64el"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-ppc64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",+ "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",+ "cpu": [+ "ppc64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-riscv64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",+ "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",+ "cpu": [+ "riscv64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-s390x": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",+ "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",+ "cpu": [+ "s390x"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/linux-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",+ "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/netbsd-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",+ "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "netbsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/netbsd-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",+ "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "netbsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/openbsd-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",+ "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "openbsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/openbsd-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",+ "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "openbsd"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/openharmony-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",+ "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "openharmony"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/sunos-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",+ "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "sunos"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/win32-arm64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",+ "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/win32-ia32": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",+ "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",+ "cpu": [+ "ia32"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@esbuild/win32-x64": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",+ "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ],+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/@jridgewell/sourcemap-codec": {+ "version": "1.5.5",+ "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",+ "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/@napi-rs/lzma-linux-x64-gnu": {+ "version": "1.5.1",+ "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz",+ "integrity": "sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ],+ "engines": {+ "node": "^22.20 || ^24.12 || >=25"+ }+ },+ "node_modules/@rollup/rollup-android-arm-eabi": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.5.tgz",+ "integrity": "sha512-jfkGfTwhQpsiSckPF8r9bU3pn3vyd72NlWaO+TgEO6WPSDnUhXzrNYCHBMOYj0ACaUgjm6eERLF+XV9a6RstoA==",+ "cpu": [+ "arm"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "android"+ ]+ },+ "node_modules/@rollup/rollup-android-arm64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.5.tgz",+ "integrity": "sha512-oGVqyQlxnrz9/ty89oHpU857VUHEl5/Xu4R2lS+aivCTrNnSsbiENzTnNaBsjxH0CNWGPhzHArOLFwo+oKXveA==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "android"+ ]+ },+ "node_modules/@rollup/rollup-darwin-arm64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.5.tgz",+ "integrity": "sha512-bW7B8xMEq8n99Q3ieEcPRGuphurdZAaFzQc9Efyyw3FL6DZO6pMy9xhdN+kBoD7Sy05xNXSr4OyPPnpkYriS/A==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ]+ },+ "node_modules/@rollup/rollup-darwin-x64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.5.tgz",+ "integrity": "sha512-YSwBS86QeHOGlrxJ1PSOIZSkzRL/JmKeunhc+lV6M1a6En8QuVCD/T/qIA0J4Gd2Y86RIOBYrLcOUtqGh9+/1w==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ]+ },+ "node_modules/@rollup/rollup-freebsd-arm64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.5.tgz",+ "integrity": "sha512-2fST8lILgl7cKbme/1KDdPCmbXbG+gqoV3bHp19L0ypX/3akYMBVdOunPleRCwonoLnXOZ/0F+Mt/v8POFmfcQ==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "freebsd"+ ]+ },+ "node_modules/@rollup/rollup-freebsd-x64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.5.tgz",+ "integrity": "sha512-cpIxQCP9J+EVad0a6LO1kY3ZGODlk80VlI+2I96B8xMcdHZ4pLVhfQ49JFpYqjPF91FFkQWftf57YlDcTiw9yQ==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "freebsd"+ ]+ },+ "node_modules/@rollup/rollup-linux-arm-gnueabihf": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.5.tgz",+ "integrity": "sha512-r9fGh3eFs3e/udWh5ZjXQtxiYK/xoFxQaYR/cELxac/Udkl5Th+IsFm0CX3Kl9hmUH/we7EoMpjJgeQNnE0+IA==",+ "cpu": [+ "arm"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-arm-musleabihf": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.5.tgz",+ "integrity": "sha512-xdvFdp7OM6KLJviJT2g/YuRSUjnZgGHk4RNgwIbN7X6cPugOucV60DdHXWzsBVCUdrGb6qSXnJQrrAKMmQuj3Q==",+ "cpu": [+ "arm"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-arm64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.5.tgz",+ "integrity": "sha512-rRqILAndyzHzP7T9NFQrq+4HFWNhqkqkKur7eiBpfLmz01PO0JKx5Vchu3YllE4YXI/Ftgq/szrDWg5GJ0mI8g==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-arm64-musl": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.5.tgz",+ "integrity": "sha512-Gf4X3qVMucayUvux6aXXPgXovocSFUC0rrffDuPI/S2nHhNMhjcZxsrAFYCOF350PRreW1XwzFj3CT/3bKsWCw==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-loong64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.5.tgz",+ "integrity": "sha512-+s5qA0TNM0qm8PK/a5gt/1Hpx+NV08uSuCncvhziIlQzT6AEV2fnUQo7eBtFTFO0nA9scauvoR2HusfXmQnO4w==",+ "cpu": [+ "loong64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-loong64-musl": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.5.tgz",+ "integrity": "sha512-ybb6QvWwWJCbBWqERpc8K3pYVGIrXlG8MEQ8IIuJY6Y9KdHQxoFoNyfkAOtKn1VHu3KuLidXvwrvGR1mEjeWCw==",+ "cpu": [+ "loong64"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-ppc64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.5.tgz",+ "integrity": "sha512-nZb1DtnOyhCmYvsC8A2CwOkopVg+IS1+fPUa7rMOAXtNw5+lLCLLPqd6XAiNrGtoQKsbvIBOwsHnBH/3wnb4HQ==",+ "cpu": [+ "ppc64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-ppc64-musl": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.5.tgz",+ "integrity": "sha512-yMbj63Sp89ryrXLWyz+sy+fYD2HpOnMCLGbe4Oa1smclFSUukdtD/BgdiHaAetJNb74URD8U4hM+qG5KVzMEkg==",+ "cpu": [+ "ppc64"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-riscv64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.5.tgz",+ "integrity": "sha512-mhoan3OJw2kYV/e1jtIdmvUZgyBFeA6zGWsOswmR0Tg19TQbowZuR+JMLID6spbbBN7Zee2ejrgmy3+FxGrIdA==",+ "cpu": [+ "riscv64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-riscv64-musl": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.5.tgz",+ "integrity": "sha512-5ZTLmjWbb1VZdjuyhe83K/8QO0/h11midQCBP+X5OYn32ra7eOBoM0ZqtaY4nkgNsYgmdVhMYPoyVPTjUpHf3w==",+ "cpu": [+ "riscv64"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-s390x-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.5.tgz",+ "integrity": "sha512-m53kG+br6PGxOTmgBEM2DHSDs9RVjsyEbUwjJPJGTFm1grWOG8EKJggDCTb60unD4Tjby8fi7/m9XfkEWasVWg==",+ "cpu": [+ "s390x"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-x64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.5.tgz",+ "integrity": "sha512-6RHPJR1g/uvdYU8uXBnfq3nlqyZCP82Fr6NHgfGoaIeSh0YEqnX/x6uA9MmJJbnSH7swqX4F+CkGdUF+6doiQA==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "libc": [+ "glibc"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-linux-x64-musl": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.5.tgz",+ "integrity": "sha512-xs+OXQtEXgpXT0DmA5+U3qnRZHdCST/5HRQxS8wSPZTUZN/EMWeHuSIod32LQklTBZBV9DyfncKBQ8n5V3eFdw==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "libc": [+ "musl"+ ],+ "license": "MIT",+ "optional": true,+ "os": [+ "linux"+ ]+ },+ "node_modules/@rollup/rollup-openbsd-x64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.5.tgz",+ "integrity": "sha512-e7hD+sl3s+mcLQDZ8pbudBVsdG6r5yN4w3LqG2TJ8sQHDpblWj5lrJs/3m01Cvlxbt4x13zu5thLjgypgtkYzw==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "openbsd"+ ]+ },+ "node_modules/@rollup/rollup-openharmony-arm64": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.5.tgz",+ "integrity": "sha512-GiyJaCf+WpMub/17aPcKk27QMl5W6f+KhdPTjlFOn5akH5Wa/DCM9Stdx5cDfmasyKB08MqpVQ1uJE2RkkpbXg==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "openharmony"+ ]+ },+ "node_modules/@rollup/rollup-win32-arm64-msvc": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.5.tgz",+ "integrity": "sha512-+OQ8U2DdoEfXl8T4Fb18AjmEwbXMerKDKCL8yCPAYhKCEEKoul7rkbeGCBFCbAlaGaa7pmtRTpkAJM2LE/i5FA==",+ "cpu": [+ "arm64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ]+ },+ "node_modules/@rollup/rollup-win32-ia32-msvc": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.5.tgz",+ "integrity": "sha512-KanvAZrPKbDBFwrgiU9yEVpQoox9QPV1WZOXX7HudJQY+eSlu82CtWxDU8WtuRRvtN5EGkLczkd6Y6DTcvm9wA==",+ "cpu": [+ "ia32"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ]+ },+ "node_modules/@rollup/rollup-win32-x64-gnu": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.5.tgz",+ "integrity": "sha512-1aC3UEWTtRl3RK3VpDJ/Tqk1XI4SLTmXIthAq6wRWo8XiSXJNd+VprJM4/1P4+i6HIaFEFlVi9sTTziniD2tOQ==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ]+ },+ "node_modules/@rollup/rollup-win32-x64-msvc": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.5.tgz",+ "integrity": "sha512-/gDJaRs4gl0NPIwqCz+6PkpmhhjRAD2j6P4rSNHBzUkO3naEx2mIU0pRle1vUNRQ7mE/+8OOeXLTv/J56FKiQg==",+ "cpu": [+ "x64"+ ],+ "dev": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "win32"+ ]+ },+ "node_modules/@types/chai": {+ "version": "5.2.3",+ "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",+ "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/deep-eql": "*",+ "assertion-error": "^2.0.1"+ }+ },+ "node_modules/@types/deep-eql": {+ "version": "4.0.2",+ "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",+ "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/@types/estree": {+ "version": "1.0.9",+ "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",+ "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/@types/node": {+ "version": "20.19.43",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",+ "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",+ "license": "MIT",+ "dependencies": {+ "undici-types": "~6.21.0"+ }+ },+ "node_modules/@vitest/expect": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.7.tgz",+ "integrity": "sha512-E8eBXaKibuvH2pSZErOjdVb5vF4PbKYcrnluBTYxEk1l/VhhwZg1kZQsdtjq+CsF5CFydf2Rdkz7jDHKSisi3w==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/chai": "^5.2.2",+ "@vitest/spy": "3.2.7",+ "@vitest/utils": "3.2.7",+ "chai": "^5.2.0",+ "tinyrainbow": "^2.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/mocker": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.7.tgz",+ "integrity": "sha512-Trr0hYO9CM3Wj6ksWHRhK9IZpIY6wTMO5u/MqXurMxT57sWBaOPEtP3Oq60ihZuh5JsiagKfz95OcxdEP6dBrA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/spy": "3.2.7",+ "estree-walker": "^3.0.3",+ "magic-string": "^0.30.17"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ },+ "peerDependencies": {+ "msw": "^2.4.9",+ "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"+ },+ "peerDependenciesMeta": {+ "msw": {+ "optional": true+ },+ "vite": {+ "optional": true+ }+ }+ },+ "node_modules/@vitest/pretty-format": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.7.tgz",+ "integrity": "sha512-KUHlwqVu0sRlhCdyPdQ/wBoTfRahjUky1MubOmYw9fWfIZy1gNoHpuaaQBPAaMaVYdQYHJLurzj8ECCj5OwTqA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "tinyrainbow": "^2.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/runner": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.7.tgz",+ "integrity": "sha512-sB9y4ovltoQP+WaUPwmSxO9WIg9Ig694Di5PalVPsYHklAdE027mehpWF2SQSVq+k6sFgaivbTjTJwZLSHbedA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/utils": "3.2.7",+ "pathe": "^2.0.3",+ "strip-literal": "^3.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/snapshot": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.7.tgz",+ "integrity": "sha512-7C+MwShwtBSI5Buwoyg3s/iY1eHL9PKAf+O1wVh/TdnjXUtkoL/9YQtre90i4MtNXM6edP1wJ2zOBpfCyhIS7g==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/pretty-format": "3.2.7",+ "magic-string": "^0.30.17",+ "pathe": "^2.0.3"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/spy": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.7.tgz",+ "integrity": "sha512-Q2eQGI6d2L/hBtZ0qNuKcAGid68XK6cv1xsoaIma6PaJhHPoqcEJhYpXZ/5myCMqkNgtP6UKuBhbc0nHKnrkuQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "tinyspy": "^4.0.3"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/@vitest/utils": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.7.tgz",+ "integrity": "sha512-x6BDOd7dyo3PFLY3I9/HJ25X/6OurhGXk2/B9gOZNPF7XDVjeBK4k01lQE5uvDpbuheErh91qYuE1E2OEjK3Rw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@vitest/pretty-format": "3.2.7",+ "loupe": "^3.1.4",+ "tinyrainbow": "^2.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/assertion-error": {+ "version": "2.0.1",+ "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",+ "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=12"+ }+ },+ "node_modules/cac": {+ "version": "6.7.14",+ "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",+ "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=8"+ }+ },+ "node_modules/chai": {+ "version": "5.3.3",+ "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",+ "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "assertion-error": "^2.0.1",+ "check-error": "^2.1.1",+ "deep-eql": "^5.0.1",+ "loupe": "^3.1.0",+ "pathval": "^2.0.0"+ },+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/check-error": {+ "version": "2.1.3",+ "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",+ "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">= 16"+ }+ },+ "node_modules/debug": {+ "version": "4.4.3",+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",+ "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "ms": "^2.1.3"+ },+ "engines": {+ "node": ">=6.0"+ },+ "peerDependenciesMeta": {+ "supports-color": {+ "optional": true+ }+ }+ },+ "node_modules/deep-eql": {+ "version": "5.0.2",+ "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",+ "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=6"+ }+ },+ "node_modules/es-module-lexer": {+ "version": "1.7.0",+ "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",+ "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/esbuild": {+ "version": "0.28.2",+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",+ "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",+ "dev": true,+ "hasInstallScript": true,+ "license": "MIT",+ "bin": {+ "esbuild": "bin/esbuild"+ },+ "engines": {+ "node": ">=18"+ },+ "optionalDependencies": {+ "@esbuild/aix-ppc64": "0.28.2",+ "@esbuild/android-arm": "0.28.2",+ "@esbuild/android-arm64": "0.28.2",+ "@esbuild/android-x64": "0.28.2",+ "@esbuild/darwin-arm64": "0.28.2",+ "@esbuild/darwin-x64": "0.28.2",+ "@esbuild/freebsd-arm64": "0.28.2",+ "@esbuild/freebsd-x64": "0.28.2",+ "@esbuild/linux-arm": "0.28.2",+ "@esbuild/linux-arm64": "0.28.2",+ "@esbuild/linux-ia32": "0.28.2",+ "@esbuild/linux-loong64": "0.28.2",+ "@esbuild/linux-mips64el": "0.28.2",+ "@esbuild/linux-ppc64": "0.28.2",+ "@esbuild/linux-riscv64": "0.28.2",+ "@esbuild/linux-s390x": "0.28.2",+ "@esbuild/linux-x64": "0.28.2",+ "@esbuild/netbsd-arm64": "0.28.2",+ "@esbuild/netbsd-x64": "0.28.2",+ "@esbuild/openbsd-arm64": "0.28.2",+ "@esbuild/openbsd-x64": "0.28.2",+ "@esbuild/openharmony-arm64": "0.28.2",+ "@esbuild/sunos-x64": "0.28.2",+ "@esbuild/win32-arm64": "0.28.2",+ "@esbuild/win32-ia32": "0.28.2",+ "@esbuild/win32-x64": "0.28.2"+ }+ },+ "node_modules/estree-walker": {+ "version": "3.0.3",+ "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",+ "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/estree": "^1.0.0"+ }+ },+ "node_modules/example-node-quickstart": {+ "resolved": "examples/node-quickstart",+ "link": true+ },+ "node_modules/expect-type": {+ "version": "1.4.0",+ "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",+ "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",+ "dev": true,+ "license": "Apache-2.0",+ "engines": {+ "node": ">=12.0.0"+ }+ },+ "node_modules/fdir": {+ "version": "6.5.0",+ "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",+ "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=12.0.0"+ },+ "peerDependencies": {+ "picomatch": "^3 || ^4"+ },+ "peerDependenciesMeta": {+ "picomatch": {+ "optional": true+ }+ }+ },+ "node_modules/fsevents": {+ "version": "2.3.3",+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",+ "dev": true,+ "hasInstallScript": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ],+ "engines": {+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"+ }+ },+ "node_modules/js-tokens": {+ "version": "9.0.1",+ "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",+ "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/loupe": {+ "version": "3.2.1",+ "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",+ "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/magic-string": {+ "version": "0.30.21",+ "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",+ "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@jridgewell/sourcemap-codec": "^1.5.5"+ }+ },+ "node_modules/ms": {+ "version": "2.1.3",+ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",+ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/nanoid": {+ "version": "3.3.18",+ "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",+ "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",+ "dev": true,+ "funding": [+ {+ "type": "github",+ "url": "https://github.com/sponsors/ai"+ }+ ],+ "license": "MIT",+ "bin": {+ "nanoid": "bin/nanoid.cjs"+ },+ "engines": {+ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"+ }+ },+ "node_modules/pathe": {+ "version": "2.0.3",+ "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",+ "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/pathval": {+ "version": "2.0.1",+ "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",+ "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">= 14.16"+ }+ },+ "node_modules/picocolors": {+ "version": "1.1.1",+ "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",+ "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",+ "dev": true,+ "license": "ISC"+ },+ "node_modules/picomatch": {+ "version": "4.0.7",+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",+ "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=12"+ },+ "funding": {+ "url": "https://github.com/sponsors/jonschlinkert"+ }+ },+ "node_modules/postcss": {+ "version": "8.5.26",+ "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",+ "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",+ "dev": true,+ "funding": [+ {+ "type": "opencollective",+ "url": "https://opencollective.com/postcss/"+ },+ {+ "type": "tidelift",+ "url": "https://tidelift.com/funding/github/npm/postcss"+ },+ {+ "type": "github",+ "url": "https://github.com/sponsors/ai"+ }+ ],+ "license": "MIT",+ "dependencies": {+ "nanoid": "^3.3.17",+ "picocolors": "^1.1.1",+ "source-map-js": "^1.2.1"+ },+ "engines": {+ "node": "^10 || ^12 || >=14"+ }+ },+ "node_modules/rollup": {+ "version": "4.62.5",+ "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.5.tgz",+ "integrity": "sha512-/tqMfgP7GPA3PHhCmuiS4vIjrSVhHLgY++i+dhbG462euyAj7FpM4D9uq1X3BgjlqRdpcOrYhcQtfiQLNc8tqw==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/estree": "1.0.9"+ },+ "bin": {+ "rollup": "dist/bin/rollup"+ },+ "engines": {+ "node": ">=18.0.0",+ "npm": ">=8.0.0"+ },+ "optionalDependencies": {+ "@napi-rs/lzma-linux-x64-gnu": "1.5.1",+ "@rollup/rollup-android-arm-eabi": "4.62.5",+ "@rollup/rollup-android-arm64": "4.62.5",+ "@rollup/rollup-darwin-arm64": "4.62.5",+ "@rollup/rollup-darwin-x64": "4.62.5",+ "@rollup/rollup-freebsd-arm64": "4.62.5",+ "@rollup/rollup-freebsd-x64": "4.62.5",+ "@rollup/rollup-linux-arm-gnueabihf": "4.62.5",+ "@rollup/rollup-linux-arm-musleabihf": "4.62.5",+ "@rollup/rollup-linux-arm64-gnu": "4.62.5",+ "@rollup/rollup-linux-arm64-musl": "4.62.5",+ "@rollup/rollup-linux-loong64-gnu": "4.62.5",+ "@rollup/rollup-linux-loong64-musl": "4.62.5",+ "@rollup/rollup-linux-ppc64-gnu": "4.62.5",+ "@rollup/rollup-linux-ppc64-musl": "4.62.5",+ "@rollup/rollup-linux-riscv64-gnu": "4.62.5",+ "@rollup/rollup-linux-riscv64-musl": "4.62.5",+ "@rollup/rollup-linux-s390x-gnu": "4.62.5",+ "@rollup/rollup-linux-x64-gnu": "4.62.5",+ "@rollup/rollup-linux-x64-musl": "4.62.5",+ "@rollup/rollup-openbsd-x64": "4.62.5",+ "@rollup/rollup-openharmony-arm64": "4.62.5",+ "@rollup/rollup-win32-arm64-msvc": "4.62.5",+ "@rollup/rollup-win32-ia32-msvc": "4.62.5",+ "@rollup/rollup-win32-x64-gnu": "4.62.5",+ "@rollup/rollup-win32-x64-msvc": "4.62.5",+ "fsevents": "~2.3.2"+ }+ },+ "node_modules/siginfo": {+ "version": "2.0.0",+ "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",+ "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",+ "dev": true,+ "license": "ISC"+ },+ "node_modules/source-map-js": {+ "version": "1.2.1",+ "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",+ "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",+ "dev": true,+ "license": "BSD-3-Clause",+ "engines": {+ "node": ">=0.10.0"+ }+ },+ "node_modules/stackback": {+ "version": "0.0.2",+ "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",+ "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/std-env": {+ "version": "3.10.0",+ "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",+ "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/strip-literal": {+ "version": "3.1.0",+ "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-3.1.0.tgz",+ "integrity": "sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "js-tokens": "^9.0.1"+ },+ "funding": {+ "url": "https://github.com/sponsors/antfu"+ }+ },+ "node_modules/tinybench": {+ "version": "2.9.0",+ "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",+ "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/tinyexec": {+ "version": "0.3.2",+ "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",+ "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",+ "dev": true,+ "license": "MIT"+ },+ "node_modules/tinyglobby": {+ "version": "0.2.17",+ "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",+ "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "fdir": "^6.5.0",+ "picomatch": "^4.0.4"+ },+ "engines": {+ "node": ">=12.0.0"+ },+ "funding": {+ "url": "https://github.com/sponsors/SuperchupuDev"+ }+ },+ "node_modules/tinypool": {+ "version": "1.1.1",+ "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",+ "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": "^18.0.0 || >=20.0.0"+ }+ },+ "node_modules/tinyrainbow": {+ "version": "2.0.0",+ "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-2.0.0.tgz",+ "integrity": "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=14.0.0"+ }+ },+ "node_modules/tinyspy": {+ "version": "4.0.4",+ "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",+ "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=14.0.0"+ }+ },+ "node_modules/typescript": {+ "version": "5.9.3",+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "tsc": "bin/tsc",+ "tsserver": "bin/tsserver"+ },+ "engines": {+ "node": ">=14.17"+ }+ },+ "node_modules/undici-types": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",+ "license": "MIT"+ },+ "node_modules/vite": {+ "version": "7.3.6",+ "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.6.tgz",+ "integrity": "sha512-4XP60spRGjSZFf1qYH+dJIkK2znL3zQfl9KkOV9MkkRR/3Dls0dxaBsQPTloEc5BLXWPL9vsOxopxyKoMmDueg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "esbuild": "^0.27.0 || ^0.28.0",+ "fdir": "^6.5.0",+ "picomatch": "^4.0.3",+ "postcss": "^8.5.6",+ "rollup": "^4.43.0",+ "tinyglobby": "^0.2.15"+ },+ "bin": {+ "vite": "bin/vite.js"+ },+ "engines": {+ "node": "^20.19.0 || >=22.12.0"+ },+ "funding": {+ "url": "https://github.com/vitejs/vite?sponsor=1"+ },+ "optionalDependencies": {+ "fsevents": "~2.3.3"+ },+ "peerDependencies": {+ "@types/node": "^20.19.0 || >=22.12.0",+ "jiti": ">=1.21.0",+ "less": "^4.0.0",+ "lightningcss": "^1.21.0",+ "sass": "^1.70.0",+ "sass-embedded": "^1.70.0",+ "stylus": ">=0.54.8",+ "sugarss": "^5.0.0",+ "terser": "^5.16.0",+ "tsx": "^4.8.1",+ "yaml": "^2.4.2"+ },+ "peerDependenciesMeta": {+ "@types/node": {+ "optional": true+ },+ "jiti": {+ "optional": true+ },+ "less": {+ "optional": true+ },+ "lightningcss": {+ "optional": true+ },+ "sass": {+ "optional": true+ },+ "sass-embedded": {+ "optional": true+ },+ "stylus": {+ "optional": true+ },+ "sugarss": {+ "optional": true+ },+ "terser": {+ "optional": true+ },+ "tsx": {+ "optional": true+ },+ "yaml": {+ "optional": true+ }+ }+ },+ "node_modules/vite-node": {+ "version": "3.2.4",+ "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-3.2.4.tgz",+ "integrity": "sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "cac": "^6.7.14",+ "debug": "^4.4.1",+ "es-module-lexer": "^1.7.0",+ "pathe": "^2.0.3",+ "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"+ },+ "bin": {+ "vite-node": "vite-node.mjs"+ },+ "engines": {+ "node": "^18.0.0 || ^20.0.0 || >=22.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ }+ },+ "node_modules/vitest": {+ "version": "3.2.7",+ "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.7.tgz",+ "integrity": "sha512-KrxIJ62Fd89gfysR4WotlgZABiz2dqFPgqGzX7s+CwsqLFomRH7777ZcrOD6+WVAh7khPQP41A+BKbpcJFrdEg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "@types/chai": "^5.2.2",+ "@vitest/expect": "3.2.7",+ "@vitest/mocker": "3.2.7",+ "@vitest/pretty-format": "^3.2.7",+ "@vitest/runner": "3.2.7",+ "@vitest/snapshot": "3.2.7",+ "@vitest/spy": "3.2.7",+ "@vitest/utils": "3.2.7",+ "chai": "^5.2.0",+ "debug": "^4.4.1",+ "expect-type": "^1.2.1",+ "magic-string": "^0.30.17",+ "pathe": "^2.0.3",+ "picomatch": "^4.0.2",+ "std-env": "^3.9.0",+ "tinybench": "^2.9.0",+ "tinyexec": "^0.3.2",+ "tinyglobby": "^0.2.14",+ "tinypool": "^1.1.1",+ "tinyrainbow": "^2.0.0",+ "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0",+ "vite-node": "3.2.4",+ "why-is-node-running": "^2.3.0"+ },+ "bin": {+ "vitest": "vitest.mjs"+ },+ "engines": {+ "node": "^18.0.0 || ^20.0.0 || >=22.0.0"+ },+ "funding": {+ "url": "https://opencollective.com/vitest"+ },+ "peerDependencies": {+ "@edge-runtime/vm": "*",+ "@types/debug": "^4.1.12",+ "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",+ "@vitest/browser": "3.2.7",+ "@vitest/ui": "3.2.7",+ "happy-dom": "*",+ "jsdom": "*"+ },+ "peerDependenciesMeta": {+ "@edge-runtime/vm": {+ "optional": true+ },+ "@types/debug": {+ "optional": true+ },+ "@types/node": {+ "optional": true+ },+ "@vitest/browser": {+ "optional": true+ },+ "@vitest/ui": {+ "optional": true+ },+ "happy-dom": {+ "optional": true+ },+ "jsdom": {+ "optional": true+ }+ }+ },+ "node_modules/why-is-node-running": {+ "version": "2.3.0",+ "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",+ "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "siginfo": "^2.0.0",+ "stackback": "0.0.2"+ },+ "bin": {+ "why-is-node-running": "cli.js"+ },+ "engines": {+ "node": ">=8"+ }+ },+ "packages/core": {+ "name": "@byoc/core",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "dependencies": {+ "@types/node": ">=20"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "packages/google-drive": {+ "name": "@byoc/google-drive",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "dependencies": {+ "@byoc/core": "^0.2.1",+ "@types/node": ">=20"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "packages/provider-sdk": {+ "name": "@byoc/provider-sdk",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "packages/s3-compatible": {+ "name": "@byoc/s3-compatible",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "packages/webdav": {+ "name": "@byoc/webdav",+ "version": "0.2.1",+ "license": "Apache-2.0",+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "engines": {+ "node": ">=20"+ }+ }+ }+}diff --git a/package.json b/package.jsonnew file mode 100644index 0000000..1ac7a2b--- /dev/null+++ b/package.json@@ -0,0 +1,35 @@+{+ "name": "byoc-monorepo",+ "version": "0.2.1",+ "private": true,+ "description": "BYOC (Bring Your Own Cloud) \u2014 Universal Storage Abstraction Layer",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "https://github.com/Ajayvarmaramineni/BYOC.git"+ },+ "workspaces": [+ "packages/*",+ "examples/*"+ ],+ "scripts": {+ "build": "npm run build --workspaces --if-present",+ "test": "vitest run",+ "test:watch": "vitest",+ "typecheck": "tsc -b packages/core packages/google-drive packages/s3-compatible packages/webdav packages/provider-sdk examples/node-quickstart",+ "clean": "rm -rf node_modules packages/*/node_modules packages/*/dist examples/*/node_modules"+ },+ "devDependencies": {+ "@types/node": "^20.14.0",+ "typescript": "^5.4.5",+ "vitest": "^3.0.0"+ },+ "packageManager": "[email protected]",+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ }+}diff --git a/packages/core/LICENSE b/packages/core/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/packages/core/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/packages/core/README.md b/packages/core/README.mdnew file mode 100644index 0000000..95c5cd1--- /dev/null+++ b/packages/core/README.md@@ -0,0 +1,83 @@+# @byoc/core++Universal storage abstraction for **BYOC (Bring Your Own Cloud)**: one API for storage that end users, organizations, or infrastructure teams already own.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Requires at least one provider adapter.++## Install++```bash+npm install @byoc/core+# plus an adapter+npm install @byoc/google-drive # or @byoc/s3-compatible, @byoc/webdav+```++## Usage++```ts+import { BYOC } from "@byoc/core";+import { GoogleDriveProvider } from "@byoc/google-drive";++const storage = new BYOC({+ provider: new GoogleDriveProvider({+ auth: { clientId: process.env.GOOGLE_CLIENT_ID! },+ rootFolderName: "MyApplication"+ })+});++await storage.connect();++await storage.writeText("documents/welcome.md", "# Hello from BYOC!");+const content = await storage.readText("documents/welcome.md");+```++## What's in this package++| Export | Purpose |+| :--- | :--- |+| `BYOC` | The universal client: upload, download, list, delete, move, quota |+| `BYOCProvider` | The interface every adapter implements |+| `MigrationEngine` | Stream-piped transfer between any two registered providers |+| `E2EECrypto`, `EncryptedStorageWrapper` | Client-side AES-256-GCM encryption over any provider |+| `StorageError`, `BYOCErrorCode` | Provider-neutral error taxonomy with `retryable` flags |+| `normalizeVirtualPath`, `encodePathSegments` | Path sanitization and RFC 3986 encoding |+| `SafeLogger` | Logging with automatic token/credential redaction |+| `withRetry` | Exponential backoff for rate-limited providers |++## Multi-provider and migration++```ts+const storage = new BYOC({+ providers: [gdrive, s3, webdav],+ defaultProviderId: "google-drive"+});++storage.useProvider("s3-compatible");++const report = await storage.migrate({+ from: "google-drive",+ to: "webdav",+ paths: ["documents/report.pdf"],+ onProgress: (p) => console.log(`${p.currentFile} (${p.percentage}%)`)+});+```++## Client-side encryption++`EncryptedStorageWrapper` wraps any provider so plaintext never leaves the process. Payloads are buffered, so it does not currently support resumable/streaming uploads; the wrapper reports `resumableUploads: false` accordingly.++```ts+import { EncryptedStorageWrapper } from "@byoc/core";++const secure = new EncryptedStorageWrapper(gdrive, {+ passphrase: process.env.USER_PASSPHRASE!+});+```++## Provider independence++`@byoc/core` contains no provider-specific concepts. Drive file IDs, S3 object keys, and WebDAV collections stay private to their adapters. Core speaks only in `path`, `id`, `providerId`, `StorageObject`, and `StorageQuota`.++## License++[Apache-2.0](./LICENSE)diff --git a/packages/core/package.json b/packages/core/package.jsonnew file mode 100644index 0000000..32aaecf--- /dev/null+++ b/packages/core/package.json@@ -0,0 +1,54 @@+{+ "name": "@byoc/core",+ "version": "0.2.1",+ "description": "Core universal storage abstraction for BYOC (Bring Your Own Cloud)",+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js",+ "default": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "!dist/tsconfig.tsbuildinfo",+ "README.md",+ "LICENSE"+ ],+ "scripts": {+ "build": "tsc -b",+ "clean": "rm -rf dist tsconfig.tsbuildinfo"+ },+ "keywords": [+ "byoc",+ "cloud-storage",+ "storage-abstraction",+ "multi-cloud",+ "personal-cloud",+ "self-hosted"+ ],+ "author": "Ajay Ramineni",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Ajayvarmaramineni/BYOC.git",+ "directory": "packages/core"+ },+ "publishConfig": {+ "access": "public"+ },+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC/tree/main/packages/core#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ },+ "sideEffects": false,+ "dependencies": {+ "@types/node": ">=20"+ }+}diff --git a/packages/core/src/client/byoc.ts b/packages/core/src/client/byoc.tsnew file mode 100644index 0000000..6b241d1--- /dev/null+++ b/packages/core/src/client/byoc.ts@@ -0,0 +1,435 @@+import type {+ BYOCProvider,+ ProviderCapabilities,+ ProviderManifest+} from "../types/provider.js";+import type {+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+ BackupOptions+} from "../types/storage.js";+import { normalizeVirtualPath } from "../paths/resolver.js";+import { BYOCErrorCode } from "../errors/codes.js";+import { StorageError } from "../errors/storage-error.js";+import { type BYOCLogger, SafeLogger, SilentLogger } from "../utils/logger.js";+import { lookupMimeType } from "../utils/mime.js";+import {+ MigrationEngine,+ type ConflictStrategy,+ type MigrationProgress,+ type MigrationReport+} from "../migration/engine.js";++export interface BYOCConfig {+ /** Single default storage provider */+ provider?: BYOCProvider;+ /** Array of supported storage providers for multi-provider routing */+ providers?: BYOCProvider[];+ /** Optional initial provider ID to activate if multiple providers are configured */+ defaultProviderId?: string;+ /** Optional custom logger instance or "silent" to disable logging */+ logger?: BYOCLogger | "silent";+ /** Optional maximum allowed file size in bytes */+ maxFileSizeBytes?: number;+}++/**+ * BYOC — Universal Client for User-Owned, Self-Hosted, and Multi-Cloud Storage.+ */+export class BYOC {+ private readonly providerRegistry = new Map<string, BYOCProvider>();+ private readonly logger: BYOCLogger;+ private readonly maxFileSizeBytes?: number;+ private currentProvider: BYOCProvider;++ constructor(config: BYOCConfig) {+ if (!config) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "BYOC initialization failed: Configuration options must be supplied.",+ provider: "core",+ retryable: false+ });+ }++ this.logger =+ config.logger === "silent"+ ? new SilentLogger()+ : config.logger ?? new SafeLogger("info");+ this.maxFileSizeBytes = config.maxFileSizeBytes;++ const providerList: BYOCProvider[] = [];++ if (config.provider) {+ providerList.push(config.provider);+ }+ if (config.providers && Array.isArray(config.providers)) {+ providerList.push(...config.providers);+ }++ if (providerList.length === 0) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "BYOC initialization failed: At least one 'provider' adapter must be supplied.",+ provider: "core",+ retryable: false+ });+ }++ // Register all providers by their manifest ID+ for (const provider of providerList) {+ const manifest = provider.manifest();+ this.providerRegistry.set(manifest.id, provider);+ }++ // Select initial active provider+ if (config.defaultProviderId && this.providerRegistry.has(config.defaultProviderId)) {+ this.currentProvider = this.providerRegistry.get(config.defaultProviderId)!;+ } else {+ this.currentProvider = providerList[0]!;+ }+ }++ /**+ * Switches the active storage provider by its manifest ID (e.g. "google-drive", "onedrive", "cloudflare-r2").+ */+ public useProvider(providerId: string): this {+ const target = this.providerRegistry.get(providerId);+ if (!target) {+ const available = Array.from(this.providerRegistry.keys()).join(", ");+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `Provider '${providerId}' is not registered in this BYOC client. Available providers: [${available}]`,+ provider: "core",+ retryable: false+ });+ }+ this.currentProvider = target;+ return this;+ }++ /**+ * Returns a list of manifests for all registered storage providers.+ */+ public getProviders(): ProviderManifest[] {+ return Array.from(this.providerRegistry.values()).map((p) => p.manifest());+ }++ /**+ * Returns the metadata manifest of the active provider.+ */+ public manifest(): ProviderManifest {+ return this.currentProvider.manifest();+ }++ /**+ * Returns the feature capabilities supported by the active provider.+ */+ public async capabilities(): Promise<ProviderCapabilities> {+ return this.currentProvider.capabilities();+ }++ /**+ * Checks whether the active provider supports a specific capability.+ */+ public async hasCapability(capability: keyof ProviderCapabilities): Promise<boolean> {+ const caps = await this.capabilities();+ return !!caps[capability];+ }++ /**+ * Returns the active safe logger instance.+ */+ public getLogger(): BYOCLogger {+ return this.logger;+ }++ /**+ * Authenticate and initialize the connection with the active storage provider.+ */+ public async connect(): Promise<void> {+ this.logger.debug(`Connecting to provider: ${this.manifest().id}`);+ return this.currentProvider.connect();+ }++ /**+ * Disconnect and clear/revoke authentication tokens for the active provider.+ */+ public async disconnect(): Promise<void> {+ this.logger.debug(`Disconnecting from provider: ${this.manifest().id}`);+ return this.currentProvider.disconnect();+ }++ /**+ * Upload binary data to the target virtual path.+ */+ public async upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Upload requires a valid non-empty file path.",+ provider: this.manifest().id,+ retryable: false+ });+ }++ // Validate size limit if payload is in-memory+ if (this.maxFileSizeBytes !== undefined) {+ const size =+ typeof data === "string"+ ? Buffer.byteLength(data)+ : data instanceof Uint8Array || (typeof Buffer !== "undefined" && Buffer.isBuffer(data))+ ? data.byteLength+ : undefined;++ if (size !== undefined && size > this.maxFileSizeBytes) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `File size (${size} bytes) exceeds configured maximum limit of ${this.maxFileSizeBytes} bytes.`,+ provider: this.manifest().id,+ retryable: false+ });+ }+ }++ // Auto-detect MIME type if omitted+ const effectiveMimeType = options?.mimeType || lookupMimeType(normalized);++ this.logger.debug(`Uploading to ${normalized} (${effectiveMimeType}) on ${this.manifest().id}`);++ return this.currentProvider.upload(normalized, data, {+ ...options,+ mimeType: effectiveMimeType+ });+ }++ /**+ * Convenience helper to upload a UTF-8 text string directly.+ */+ public async writeText(+ path: string,+ content: string,+ options?: UploadOptions+ ): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ const mime = options?.mimeType || lookupMimeType(normalized, "text/plain; charset=utf-8");+ return this.upload(path, content, {+ ...options,+ mimeType: mime+ });+ }++ /**+ * Convenience helper to upload a binary buffer directly.+ */+ public async writeBuffer(+ path: string,+ buffer: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ return this.upload(path, buffer, options);+ }++ /**+ * Download binary data and metadata from the specified virtual path.+ */+ public async download(path: string): Promise<StorageOutput> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Download requires a valid non-empty file path.",+ provider: this.manifest().id,+ retryable: false+ });+ }+ return this.currentProvider.download(normalized);+ }++ /**+ * Convenience helper to download and decode a file directly as a UTF-8 string.+ */+ public async readText(path: string): Promise<string> {+ const output = await this.download(path);+ return output.text();+ }++ /**+ * Convenience helper to download and return a file directly as an ArrayBuffer.+ */+ public async readBuffer(path: string): Promise<ArrayBuffer> {+ const output = await this.download(path);+ return output.arrayBuffer();+ }++ /**+ * Delete the object at the specified virtual path.+ */+ public async delete(path: string): Promise<void> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Delete requires a valid non-empty file path.",+ provider: this.manifest().id,+ retryable: false+ });+ }+ return this.currentProvider.delete(normalized);+ }++ /**+ * List files and folders within an optional folder path.+ */+ public async list(path?: string): Promise<StorageObject[]> {+ const normalized = normalizeVirtualPath(path);+ return this.currentProvider.list(normalized);+ }++ /**+ * Check whether an object exists at the specified virtual path.+ */+ public async exists(path: string): Promise<boolean> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) return false;+ return this.currentProvider.exists(normalized);+ }++ /**+ * Get metadata for an object at the specified virtual path.+ */+ public async metadata(path: string): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Metadata check requires a valid non-empty file path.",+ provider: this.manifest().id,+ retryable: false+ });+ }+ return this.currentProvider.metadata(normalized);+ }++ /**+ * Create a virtual folder if supported by the provider.+ */+ public async createFolder(path: string): Promise<StorageObject> {+ const capabilities = await this.capabilities();+ if (!capabilities.folders || !this.currentProvider.createFolder) {+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: `Provider '${this.manifest().name}' does not support explicit folder creation.`,+ provider: this.manifest().id,+ retryable: false+ });+ }+ const normalized = normalizeVirtualPath(path);+ return this.currentProvider.createFolder(normalized);+ }++ /**+ * Move an object from source to destination virtual path.+ */+ public async move(source: string, destination: string): Promise<void> {+ if (!this.currentProvider.move) {+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: `Provider '${this.manifest().name}' does not support native move operations.`,+ provider: this.manifest().id,+ retryable: false+ });+ }+ const normSource = normalizeVirtualPath(source);+ const normDest = normalizeVirtualPath(destination);+ return this.currentProvider.move(normSource, normDest);+ }++ /**+ * Retrieve current storage quota usage.+ */+ public async getQuota(): Promise<StorageQuota> {+ const capabilities = await this.capabilities();+ if (!capabilities.quota || !this.currentProvider.quota) {+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: `Provider '${this.manifest().name}' does not support quota reporting.`,+ provider: this.manifest().id,+ retryable: false+ });+ }+ return this.currentProvider.quota();+ }++ /**+ * High-level backup helper to export data to the user's storage.+ */+ public async backup(+ payload: StorageInput,+ options?: BackupOptions+ ): Promise<StorageObject> {+ if (this.currentProvider.backup) {+ return this.currentProvider.backup(payload, options);+ }++ const folder = normalizeVirtualPath(options?.folder ?? "Backups");+ const filename =+ options?.filename ?? `backup-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;+ const targetPath = folder ? `${folder}/${filename}` : filename;++ return this.upload(targetPath, payload, {+ mimeType: options?.mimeType,+ onProgress: options?.onProgress+ });+ }++ /**+ * Migrates files between any two registered storage providers with zero-copy stream piping.+ */+ public async migrate(options: {+ from: string;+ to: string;+ paths: string[];+ conflictStrategy?: ConflictStrategy;+ deleteSourceAfterMigrate?: boolean;+ onProgress?: (progress: MigrationProgress) => void;+ }): Promise<MigrationReport> {+ const source = this.providerRegistry.get(options.from);+ const target = this.providerRegistry.get(options.to);++ if (!source) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `Source provider '${options.from}' is not registered in this BYOC client.`,+ provider: "core"+ });+ }++ if (!target) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `Destination provider '${options.to}' is not registered in this BYOC client.`,+ provider: "core"+ });+ }++ this.logger.info(`Starting cloud migration from ${options.from} to ${options.to} (${options.paths.length} files)`);++ return MigrationEngine.migrate({+ source,+ target,+ paths: options.paths,+ conflictStrategy: options.conflictStrategy,+ deleteSourceAfterMigrate: options.deleteSourceAfterMigrate,+ onProgress: options.onProgress+ });+ }+}diff --git a/packages/core/src/encryption/e2ee.ts b/packages/core/src/encryption/e2ee.tsnew file mode 100644index 0000000..ecb6a0f--- /dev/null+++ b/packages/core/src/encryption/e2ee.ts@@ -0,0 +1,368 @@+import crypto from "node:crypto";+import { promisify } from "node:util";+import { Readable } from "node:stream";+import { BYOCErrorCode } from "../errors/codes.js";+import { StorageError } from "../errors/storage-error.js";+import type {+ BYOCProvider,+ ProviderCapabilities,+ ProviderManifest+} from "../types/provider.js";+import type {+ StorageInput,+ StorageObject,+ StorageOutput,+ UploadOptions,+ BackupOptions,+ StorageQuota+} from "../types/storage.js";++const pbkdf2Async = promisify(crypto.pbkdf2);++export interface E2EEOptions {+ passphrase?: string;+ masterKey?: Buffer | Uint8Array;+ keyDerivationIterations?: number;+}++const E2EE_MAGIC_HEADER_V1 = Buffer.from("BYOC_E2EE_V1"); // 12 bytes (legacy v0.1 format, 100k fixed iter)+const E2EE_MAGIC_HEADER_V2 = Buffer.from("BYOC_E2EE_V2"); // 12 bytes (v0.2 format, dynamic 4-byte iter)+const ITER_LENGTH = 4; // 4-byte big-endian unsigned integer+const SALT_LENGTH = 16;+const IV_LENGTH = 12;+const TAG_LENGTH = 16;+const HEADER_LENGTH_V1 = E2EE_MAGIC_HEADER_V1.length + SALT_LENGTH + IV_LENGTH + TAG_LENGTH;+const HEADER_LENGTH_V2 = E2EE_MAGIC_HEADER_V2.length + ITER_LENGTH + SALT_LENGTH + IV_LENGTH + TAG_LENGTH;++/**+ * Accepted bounds for the envelope-encoded PBKDF2 iteration count.+ *+ * The iteration count is read from untrusted storage before the GCM tag can be+ * verified, so it must be range-checked first: a hostile 4-byte edit would+ * otherwise turn a ~50 ms decrypt into minutes of PBKDF2 occupying a libuv+ * threadpool thread. The floor rejects envelopes whose key derivation is too+ * weak to trust; the ceiling caps the work an attacker can force.+ */+const MIN_ITERATIONS = 10_000;+const MAX_ITERATIONS = 2_000_000;++/**+ * End-to-End Encryption (E2EE) Utility: Encrypts and decrypts binary payloads with AES-256-GCM.+ * Non-blocking asynchronous PBKDF2 with dynamic envelope-encoded iteration counts.+ */+export class E2EECrypto {+ private readonly masterKey: Buffer;+ private readonly iterations: number;++ constructor(options: E2EEOptions) {+ if (!options.passphrase && !options.masterKey) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "E2EECrypto requires either a 'passphrase' or 'masterKey'.",+ provider: "core"+ });+ }++ this.iterations = options.keyDerivationIterations || 600000;++ if (this.iterations < MIN_ITERATIONS || this.iterations > MAX_ITERATIONS) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `E2EECrypto 'keyDerivationIterations' must be between ${MIN_ITERATIONS} and ${MAX_ITERATIONS} (received ${this.iterations}).`,+ provider: "core",+ retryable: false+ });+ }++ if (options.masterKey) {+ this.masterKey = Buffer.from(options.masterKey);+ } else {+ this.masterKey = Buffer.from(options.passphrase!, "utf8");+ }+ }++ /**+ * Asynchronously derives a 256-bit AES key from passphrase and salt using PBKDF2.+ * Runs in the libuv threadpool to avoid blocking the event loop.+ */+ private async deriveKey(salt: Buffer, iterations: number): Promise<Buffer> {+ return pbkdf2Async(this.masterKey, salt, iterations, 32, "sha256");+ }++ /**+ * Encrypts plaintext bytes returning an envelope containing [MAGIC_V2 + ITER + SALT + IV + TAG + CIPHERTEXT].+ */+ public async encrypt(plaintext: Uint8Array | string): Promise<Uint8Array> {+ const dataBytes = typeof plaintext === "string" ? Buffer.from(plaintext, "utf8") : Buffer.from(plaintext);+ const salt = crypto.randomBytes(SALT_LENGTH);+ const iv = crypto.randomBytes(IV_LENGTH);+ const iterBuf = Buffer.alloc(ITER_LENGTH);+ iterBuf.writeUInt32BE(this.iterations, 0);++ const derivedKey = await this.deriveKey(salt, this.iterations);+ const cipher = crypto.createCipheriv("aes-256-gcm", derivedKey, iv);++ // Cryptographically bind envelope header metadata (magic + iterations + salt) as GCM AAD+ const aad = Buffer.concat([E2EE_MAGIC_HEADER_V2, iterBuf, salt]);+ cipher.setAAD(aad);++ const encrypted = Buffer.concat([cipher.update(dataBytes), cipher.final()]);+ const tag = cipher.getAuthTag();++ const output = Buffer.concat([+ E2EE_MAGIC_HEADER_V2,+ iterBuf,+ salt,+ iv,+ tag,+ encrypted+ ]);++ return new Uint8Array(output);+ }++ /**+ * Decrypts an envelope payload [MAGIC + (ITER) + SALT + IV + TAG + CIPHERTEXT] using AES-256-GCM.+ * Transparently supports both V2 (dynamic iteration) and V1 (legacy 100k iteration) envelope formats.+ */+ public async decrypt(envelopeBytes: Uint8Array): Promise<Uint8Array> {+ const buf = Buffer.from(envelopeBytes);++ if (buf.length < HEADER_LENGTH_V1) {+ throw new StorageError({+ code: BYOCErrorCode.CORRUPTED_DATA,+ message: "Invalid E2EE payload: Data is shorter than header size.",+ provider: "core"+ });+ }++ const isV2 = buf.subarray(0, E2EE_MAGIC_HEADER_V2.length).equals(E2EE_MAGIC_HEADER_V2);+ const isV1 = buf.subarray(0, E2EE_MAGIC_HEADER_V1.length).equals(E2EE_MAGIC_HEADER_V1);++ if (!isV2 && !isV1) {+ throw new StorageError({+ code: BYOCErrorCode.CORRUPTED_DATA,+ message: "Invalid E2EE payload: Missing or unrecognized magic header.",+ provider: "core"+ });+ }++ let offset = 12;+ let fileIterations: number;+ let aad: Buffer;++ if (isV2) {+ if (buf.length < HEADER_LENGTH_V2) {+ throw new StorageError({+ code: BYOCErrorCode.CORRUPTED_DATA,+ message: "Invalid E2EE V2 payload: Data is shorter than header size.",+ provider: "core"+ });+ }++ const iterBuf = buf.subarray(offset, offset + ITER_LENGTH);+ fileIterations = iterBuf.readUInt32BE(0);++ // Range-check before deriving: this value comes from untrusted storage and+ // is consumed before the GCM tag can authenticate it.+ if (fileIterations < MIN_ITERATIONS || fileIterations > MAX_ITERATIONS) {+ throw new StorageError({+ code: BYOCErrorCode.CORRUPTED_DATA,+ message: `Invalid E2EE payload: iteration count ${fileIterations} is outside the accepted range (${MIN_ITERATIONS}-${MAX_ITERATIONS}).`,+ provider: "core",+ retryable: false+ });+ }+ offset += ITER_LENGTH;++ const salt = buf.subarray(offset, offset + SALT_LENGTH);+ aad = Buffer.concat([E2EE_MAGIC_HEADER_V2, iterBuf, salt]);+ } else {+ // Legacy V1 format (fixed 100,000 iterations without explicit iter field)+ fileIterations = 100_000;+ const salt = buf.subarray(offset, offset + SALT_LENGTH);+ aad = Buffer.concat([E2EE_MAGIC_HEADER_V1, salt]);+ }++ const salt = buf.subarray(offset, offset + SALT_LENGTH);+ offset += SALT_LENGTH;+ const iv = buf.subarray(offset, offset + IV_LENGTH);+ offset += IV_LENGTH;+ const tag = buf.subarray(offset, offset + TAG_LENGTH);+ offset += TAG_LENGTH;+ const ciphertext = buf.subarray(offset);++ try {+ const derivedKey = await this.deriveKey(salt, fileIterations);+ const decipher = crypto.createDecipheriv("aes-256-gcm", derivedKey, iv);++ decipher.setAAD(aad);+ decipher.setAuthTag(tag);++ const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);+ return new Uint8Array(decrypted);+ } catch {+ throw new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "E2EE Decryption failed: Invalid passphrase or corrupted ciphertext.",+ provider: "core"+ });+ }+ }+}++/**+ * Transparent Zero-Knowledge End-to-End Encryption Wrapper for ANY BYOC Storage Provider.+ */+export class EncryptedStorageWrapper implements BYOCProvider {+ private readonly crypto: E2EECrypto;++ constructor(+ public readonly provider: BYOCProvider,+ options: E2EEOptions+ ) {+ this.crypto = new E2EECrypto(options);+ }++ public manifest(): ProviderManifest {+ const base = this.provider.manifest();+ return {+ ...base,+ name: `${base.name} (E2EE Encrypted)`+ };+ }++ public async capabilities(): Promise<ProviderCapabilities> {+ const base = await this.provider.capabilities();+ return {+ ...base,+ resumableUploads: false // Resumable multipart requires coordinated chunk encryption+ };+ }++ public async connect(): Promise<void> {+ return this.provider.connect();+ }++ public async disconnect(): Promise<void> {+ return this.provider.disconnect();+ }++ public async upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ let rawBytes: Uint8Array;++ if (typeof data === "string") {+ rawBytes = new TextEncoder().encode(data);+ } else if (data instanceof Uint8Array) {+ rawBytes = data;+ } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {+ rawBytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);+ } else if (data instanceof ArrayBuffer) {+ rawBytes = new Uint8Array(data);+ } else {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "E2EE upload currently requires buffered binary or string data.",+ provider: "core"+ });+ }++ const cipherBytes = await this.crypto.encrypt(rawBytes);+ return this.provider.upload(path, cipherBytes, {+ ...options,+ mimeType: "application/octet-stream"+ });+ }++ public async download(path: string): Promise<StorageOutput> {+ const rawOutput = await this.provider.download(path);+ const cipherBuffer = await rawOutput.arrayBuffer();+ const plainBytes = await this.crypto.decrypt(new Uint8Array(cipherBuffer));+ const plainBuf = Buffer.from(plainBytes.buffer, plainBytes.byteOffset, plainBytes.byteLength);++ return {+ stream: Readable.from([plainBuf]) as any,+ arrayBuffer: async () => plainBytes.buffer.slice(plainBytes.byteOffset, plainBytes.byteOffset + plainBytes.byteLength) as ArrayBuffer,+ text: async () => new TextDecoder().decode(plainBytes),+ metadata: {+ ...rawOutput.metadata,+ size: plainBytes.byteLength+ }+ };+ }++ public async delete(path: string): Promise<void> {+ return this.provider.delete(path);+ }++ public async list(path?: string): Promise<StorageObject[]> {+ return this.provider.list(path);+ }++ public async exists(path: string): Promise<boolean> {+ return this.provider.exists(path);+ }++ public async metadata(path: string): Promise<StorageObject> {+ return this.provider.metadata(path);+ }++ public async createFolder(path: string): Promise<StorageObject> {+ if (this.provider.createFolder) {+ return this.provider.createFolder(path);+ }+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: "CreateFolder not supported by underlying provider.",+ provider: "core"+ });+ }++ public async copy(source: string, destination: string): Promise<void> {+ if (this.provider.copy) {+ return this.provider.copy(source, destination);+ }+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: "Copy not supported by underlying provider.",+ provider: "core"+ });+ }++ public async move(source: string, destination: string): Promise<void> {+ if (this.provider.move) {+ return this.provider.move(source, destination);+ }+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: "Move not supported by underlying provider.",+ provider: "core"+ });+ }++ public async quota(): Promise<StorageQuota> {+ if (this.provider.quota) {+ return this.provider.quota();+ }+ throw new StorageError({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED,+ message: "Quota not supported by underlying provider.",+ provider: "core"+ });+ }++ public async backup(payload: StorageInput, options?: BackupOptions): Promise<StorageObject> {+ const folder = options?.folder ?? "Backups";+ const filename = options?.filename ?? `backup-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;+ const targetPath = folder ? `${folder}/${filename}` : filename;++ return this.upload(targetPath, payload, {+ mimeType: options?.mimeType ?? "application/json",+ onProgress: options?.onProgress+ });+ }+}diff --git a/packages/core/src/errors/codes.ts b/packages/core/src/errors/codes.tsnew file mode 100644index 0000000..c6d5b71--- /dev/null+++ b/packages/core/src/errors/codes.ts@@ -0,0 +1,36 @@+/**+ * Standardized error codes across all BYOC providers.+ * Core code and client layers strictly use these provider-neutral codes.+ */+export const BYOCErrorCode = {+ /** Authentication is missing, invalid, or expired. Re-auth required. */+ AUTH_REQUIRED: "BYOC_AUTH_REQUIRED",+ /** The requested object or folder path was not found. */+ OBJECT_NOT_FOUND: "BYOC_OBJECT_NOT_FOUND",+ /** Permission denied by provider (e.g. read-only access or insufficient scope). */+ PERMISSION_DENIED: "BYOC_PERMISSION_DENIED",+ /** The target cloud account has exceeded its storage quota. */+ QUOTA_EXCEEDED: "BYOC_QUOTA_EXCEEDED",+ /** Provider rate limit or query limit exceeded (temporary / retryable). */+ RATE_LIMITED: "BYOC_RATE_LIMITED",+ /** Upload failed during binary transmission or chunk assembly. */+ UPLOAD_FAILED: "BYOC_UPLOAD_FAILED",+ /** Download failed or connection was severed during streaming. */+ DOWNLOAD_FAILED: "BYOC_DOWNLOAD_FAILED",+ /** Provider service is down or temporarily unreachable (5xx/network). */+ PROVIDER_UNAVAILABLE: "BYOC_PROVIDER_UNAVAILABLE",+ /** Authentication token is expired and refresh failed. */+ TOKEN_EXPIRED: "BYOC_TOKEN_EXPIRED",+ /** Conflict detected (e.g. naming clash or concurrent modification). */+ CONFLICT: "BYOC_CONFLICT",+ /** The target object already exists on the destination provider. */+ OBJECT_ALREADY_EXISTS: "BYOC_OBJECT_ALREADY_EXISTS",+ /** The connected provider does not support the requested operation. */+ CAPABILITY_UNSUPPORTED: "BYOC_CAPABILITY_UNSUPPORTED",+ /** Input validation failed (e.g. invalid virtual path, directory traversal). */+ INVALID_INPUT: "BYOC_INVALID_INPUT",+ /** Ciphertext payload or metadata is corrupted or malformed. */+ CORRUPTED_DATA: "BYOC_CORRUPTED_DATA"+} as const;++export type BYOCErrorCode = typeof BYOCErrorCode[keyof typeof BYOCErrorCode];diff --git a/packages/core/src/errors/storage-error.ts b/packages/core/src/errors/storage-error.tsnew file mode 100644index 0000000..eee2c65--- /dev/null+++ b/packages/core/src/errors/storage-error.ts@@ -0,0 +1,58 @@+import { BYOCErrorCode } from "./codes.js";++export interface StorageErrorOptions {+ code: BYOCErrorCode;+ message: string;+ provider: string;+ statusCode?: number;+ retryable?: boolean;+ rawError?: unknown;+}++/**+ * Standard normalized error thrown by BYOC Core and all provider adapters.+ */+export class StorageError extends Error {+ public readonly code: BYOCErrorCode;+ public readonly provider: string;+ public readonly statusCode?: number;+ public readonly retryable: boolean;+ public readonly rawError?: unknown;++ constructor(options: StorageErrorOptions) {+ super(options.message);+ this.name = "StorageError";+ this.code = options.code;+ this.provider = options.provider;+ this.statusCode = options.statusCode;+ this.retryable = options.retryable ?? false;+ this.rawError = options.rawError;++ // Maintain proper stack trace in V8 engines+ if (Error.captureStackTrace) {+ Error.captureStackTrace(this, StorageError);+ }+ }++ /**+ * Helper to check if an unknown error is an instance of StorageError.+ */+ public static isStorageError(error: unknown): error is StorageError {+ return error instanceof StorageError;+ }++ /**+ * Converts the error into a clean JSON-serializable log representation+ * without leaking sensitive tokens or credential objects in rawError.+ */+ public toJSON(): Record<string, unknown> {+ return {+ name: this.name,+ code: this.code,+ message: this.message,+ provider: this.provider,+ statusCode: this.statusCode,+ retryable: this.retryable+ };+ }+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsnew file mode 100644index 0000000..9ff8b52--- /dev/null+++ b/packages/core/src/index.ts@@ -0,0 +1,57 @@+// Client+export { BYOC, type BYOCConfig } from "./client/byoc.js";++// Types+export type {+ BYOCProvider,+ ProviderManifest,+ ProviderCapabilities,+ ProviderCategory,+ AuthType+} from "./types/provider.js";++export type {+ StorageObject,+ StorageInput,+ StorageOutput,+ StorageQuota,+ UploadOptions,+ UploadProgress,+ BackupOptions+} from "./types/storage.js";++// Errors+export { BYOCErrorCode } from "./errors/codes.js";+export { StorageError, type StorageErrorOptions } from "./errors/storage-error.js";++// Path Utilities+export {+ normalizeVirtualPath,+ getBasename,+ getDirname,+ splitPath,+ rfc3986UriEncode,+ encodePathSegments+} from "./paths/resolver.js";++// Migration Engine+export {+ MigrationEngine,+ type MigrationOptions,+ type MigrationReport,+ type MigrationProgress,+ type MigrationFileResult,+ type ConflictStrategy+} from "./migration/engine.js";++// End-to-End Encryption+export {+ E2EECrypto,+ EncryptedStorageWrapper,+ type E2EEOptions+} from "./encryption/e2ee.js";++// Utilities+export { withRetry, type RetryOptions } from "./utils/retry.js";+export { SafeLogger, SilentLogger, type LogLevel, type BYOCLogger } from "./utils/logger.js";+export { lookupMimeType } from "./utils/mime.js";diff --git a/packages/core/src/migration/engine.ts b/packages/core/src/migration/engine.tsnew file mode 100644index 0000000..1dba075--- /dev/null+++ b/packages/core/src/migration/engine.ts@@ -0,0 +1,212 @@+import type { BYOCProvider } from "../types/provider.js";+import { BYOCErrorCode } from "../errors/codes.js";+import { StorageError } from "../errors/storage-error.js";+import { normalizeVirtualPath } from "../paths/resolver.js";++export type ConflictStrategy = "overwrite" | "skip" | "error";++export interface MigrationProgress {+ currentFile: string;+ filesMigrated: number;+ filesTotal: number;+ bytesTransferred: number;+ percentage: number;+}++export interface MigrationOptions {+ /** Source storage provider instance */+ source: BYOCProvider;+ /** Destination target storage provider instance */+ target: BYOCProvider;+ /** Explicit array of file paths to migrate */+ paths: string[];+ /** Conflict resolution strategy if file already exists on target (default: "overwrite") */+ conflictStrategy?: ConflictStrategy;+ /** Concurrency limit for parallel file migration (default: 4) */+ concurrency?: number;+ /** Delete file from source provider after successful target upload (default: false) */+ deleteSourceAfterMigrate?: boolean;+ /** Granular progress reporting callback */+ onProgress?: (progress: MigrationProgress) => void;+}++export interface MigrationFileResult {+ path: string;+ /**+ * `partial` means the copy to the target succeeded but the optional source+ * deletion did not — the data exists on the target, and the source copy is+ * still present. Callers retrying `failed` paths should not retry `partial`+ * ones: the transfer is done, only the source cleanup remains.+ */+ status: "migrated" | "skipped" | "failed" | "partial";+ size?: number;+ error?: string;+}++export interface MigrationReport {+ sourceProvider: string;+ targetProvider: string;+ filesTotal: number;+ filesMigrated: number;+ filesSkipped: number;+ filesFailed: number;+ /** Copied to the target, but the optional source deletion failed. */+ filesPartial: number;+ bytesTransferred: number;+ results: MigrationFileResult[];+}++/**+ * Universal Migration Engine for zero-downtime, stream-piped data transfer between clouds.+ */+export class MigrationEngine {+ /**+ * Migrates files from source provider to target provider with stream piping and concurrency control.+ */+ public static async migrate(options: MigrationOptions): Promise<MigrationReport> {+ const {+ source,+ target,+ paths,+ conflictStrategy = "overwrite",+ concurrency = 4,+ deleteSourceAfterMigrate = false,+ onProgress+ } = options;++ if (!source || !target) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Migration requires both 'source' and 'target' provider adapters.",+ provider: "migration-engine"+ });+ }++ if (!paths || paths.length === 0) {+ return {+ sourceProvider: source.manifest().id,+ targetProvider: target.manifest().id,+ filesTotal: 0,+ filesMigrated: 0,+ filesSkipped: 0,+ filesFailed: 0,+ filesPartial: 0,+ bytesTransferred: 0,+ results: []+ };+ }++ const cleanPaths = paths.map((p) => normalizeVirtualPath(p)).filter(Boolean);+ const results: MigrationFileResult[] = [];+ let bytesTransferred = 0;+ let filesMigrated = 0;+ let filesSkipped = 0;+ let filesFailed = 0;+ let filesPartial = 0;++ let currentIndex = 0;+ const safeConcurrency = Math.max(1, Math.floor(concurrency || 4));++ const emitProgress = (currentFile: string) => {+ if (onProgress) {+ const finishedCount = filesMigrated + filesSkipped + filesFailed + filesPartial;+ onProgress({+ currentFile,+ filesMigrated,+ filesTotal: cleanPaths.length,+ bytesTransferred,+ percentage: cleanPaths.length > 0 ? Math.round((finishedCount / cleanPaths.length) * 100) : 100+ });+ }+ };++ // Worker pool for bounded concurrency+ const worker = async () => {+ while (currentIndex < cleanPaths.length) {+ const index = currentIndex++;+ const filePath = cleanPaths[index]!;++ try {+ // 1. Check if target already has file+ if (conflictStrategy !== "overwrite") {+ const existsOnTarget = await target.exists(filePath);+ if (existsOnTarget) {+ if (conflictStrategy === "skip") {+ filesSkipped++;+ results.push({ path: filePath, status: "skipped" });+ emitProgress(filePath);+ continue;+ }+ if (conflictStrategy === "error") {+ throw new StorageError({+ code: BYOCErrorCode.OBJECT_ALREADY_EXISTS,+ message: `File already exists on target provider at path: "${filePath}"`,+ provider: target.manifest().id+ });+ }+ }+ }++ // 2. Download from source+ const sourceOutput = await source.download(filePath);+ const mimeType = sourceOutput.metadata.mimeType;+ const fileSize = sourceOutput.metadata.size ?? 0;++ // 3. Direct streaming pipe to target (zero-RAM buffering)+ const payload = sourceOutput.stream ?? (await sourceOutput.arrayBuffer());++ await target.upload(filePath, payload, { mimeType });++ // 4. The bytes are now on the target. Any failure past this point is a+ // cleanup failure, not a transfer failure, so it must not be reported+ // as `failed` — callers retry failures, and re-copying is wasted work.+ if (deleteSourceAfterMigrate) {+ try {+ await source.delete(filePath);+ } catch (deleteErr: unknown) {+ bytesTransferred += fileSize;+ filesPartial++;+ results.push({+ path: filePath,+ status: "partial",+ size: fileSize,+ error: `Copied to target, but source deletion failed: ${+ deleteErr instanceof Error ? deleteErr.message : String(deleteErr)+ }`+ });+ emitProgress(filePath);+ continue;+ }+ }++ // 5. Record successful migration only after all operations succeed+ bytesTransferred += fileSize;+ filesMigrated++;+ results.push({ path: filePath, status: "migrated", size: fileSize });++ emitProgress(filePath);+ } catch (err: unknown) {+ filesFailed++;+ const errorMessage = err instanceof Error ? err.message : String(err);+ results.push({ path: filePath, status: "failed", error: errorMessage });+ emitProgress(filePath);+ }+ }+ };++ const workers = Array.from({ length: Math.min(safeConcurrency, cleanPaths.length) }, () => worker());+ await Promise.all(workers);++ return {+ sourceProvider: source.manifest().id,+ targetProvider: target.manifest().id,+ filesTotal: cleanPaths.length,+ filesMigrated,+ filesSkipped,+ filesFailed,+ filesPartial,+ bytesTransferred,+ results+ };+ }+}diff --git a/packages/core/src/paths/resolver.ts b/packages/core/src/paths/resolver.tsnew file mode 100644index 0000000..5a92add--- /dev/null+++ b/packages/core/src/paths/resolver.ts@@ -0,0 +1,113 @@+import { BYOCErrorCode } from "../errors/codes.js";+import { StorageError } from "../errors/storage-error.js";++/**+ * Normalizes a virtual path:+ * - Converts backslashes to forward slashes.+ * - Collapses multiple consecutive slashes (e.g. "a///b/c" -> "a/b/c").+ * - Trims leading and trailing slashes and whitespace.+ * - Disallows directory traversal sequences (e.g. "../", "..").+ *+ * @param rawPath The input path provided by the developer+ * @returns Clean normalized POSIX path (e.g. "users/123/avatar.jpg" or "" for root)+ * @throws StorageError with BYOC_INVALID_INPUT if traversal is detected+ */+export function normalizeVirtualPath(rawPath?: string): string {+ if (!rawPath || typeof rawPath !== "string") {+ return "";+ }++ // Trim whitespace, strip control characters (NUL, newlines, etc.), and replace Windows backslashes+ let path = rawPath.replace(/[\x00-\x1F\x7F]/g, "").trim().replace(/\\/g, "/");++ // Collapse consecutive slashes+ path = path.replace(/\/+/g, "/");++ // Remove leading and trailing slashes+ path = path.replace(/^\/+|\/+$/g, "");++ if (!path) {+ return "";+ }++ // Split into segments and validate each segment+ const segments = path.split("/");+ const cleanSegments: string[] = [];++ for (const segment of segments) {+ const trimmed = segment.trim();++ if (trimmed === "" || trimmed === ".") {+ continue;+ }++ if (trimmed === "..") {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: `Invalid virtual path "${rawPath}": Directory traversal ("..") is forbidden.`,+ provider: "core",+ retryable: false+ });+ }++ cleanSegments.push(trimmed);+ }++ return cleanSegments.join("/");+}++/**+ * Extracts the file or folder name from a normalized path.+ * e.g. "users/123/avatar.jpg" -> "avatar.jpg"+ */+export function getBasename(path: string): string {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) return "";+ const lastSlash = normalized.lastIndexOf("/");+ return lastSlash === -1 ? normalized : normalized.slice(lastSlash + 1);+}++/**+ * Extracts the parent directory path from a normalized path.+ * e.g. "users/123/avatar.jpg" -> "users/123"+ */+export function getDirname(path: string): string {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) return "";+ const lastSlash = normalized.lastIndexOf("/");+ return lastSlash === -1 ? "" : normalized.slice(0, lastSlash);+}++/**+ * Splits a normalized path into its constituent directory/file segments.+ * e.g. "users/123/avatar.jpg" -> ["users", "123", "avatar.jpg"]+ */+export function splitPath(path: string): string[] {+ const normalized = normalizeVirtualPath(path);+ return normalized ? normalized.split("/") : [];+}++/**+ * Encodes a URI string according to RFC 3986 (converting ! ' ( ) * to hex).+ */+export function rfc3986UriEncode(str: string, encodeSlash: boolean = false): string {+ let result = encodeURIComponent(str).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);+ if (!encodeSlash) {+ result = result.replace(/%2F/g, "/");+ }+ return result;+}++/**+ * Encodes individual path segments according to RFC 3986, preserving forward slashes.+ * Safely encodes #, ?, +, &, spaces and unicode without breaking POSIX path hierarchies.+ */+export function encodePathSegments(path: string): string {+ const cleanPath = path.replace(/^\/+|\/+$/g, "");+ if (!cleanPath) return "";+ return cleanPath+ .split("/")+ .map((segment) => rfc3986UriEncode(segment, true))+ .join("/");+}+diff --git a/packages/core/src/types/provider.ts b/packages/core/src/types/provider.tsnew file mode 100644index 0000000..f94390a--- /dev/null+++ b/packages/core/src/types/provider.ts@@ -0,0 +1,103 @@+import type {+ StorageObject,+ StorageInput,+ StorageOutput,+ UploadOptions,+ BackupOptions,+ StorageQuota+} from "./storage.js";++export type ProviderCategory = "personal-cloud" | "self-hosted" | "developer-cloud";+export type AuthType = "oauth2" | "access-key" | "basic" | "local";++/**+ * Manifest describing provider metadata and identification.+ */+export interface ProviderManifest {+ readonly id: string;+ readonly name: string;+ readonly category: ProviderCategory;+ readonly authentication: AuthType;+ readonly supportsUserOwnedStorage: boolean;+ readonly adapterVersion: string;+}++/**+ * Explicit capabilities supported by a given provider.+ * Allows client applications to feature-detect without guessing.+ */+export interface ProviderCapabilities {+ readonly folders: boolean;+ readonly sharing: boolean;+ readonly publicUrls: boolean;+ readonly resumableUploads: boolean;+ readonly versioning: boolean;+ readonly quota: boolean;+ readonly serverSideCopy: boolean;+}++/**+ * Universal interface that every BYOC storage adapter must implement.+ */+export interface BYOCProvider {+ /** Returns the static or dynamic manifest for this provider */+ manifest(): ProviderManifest;++ /** Returns the capabilities supported by this provider instance */+ capabilities(): Promise<ProviderCapabilities> | ProviderCapabilities;++ /** Establish or verify connection / session to the storage backend */+ connect(): Promise<void>;++ /** Disconnect and revoke/clear active session tokens */+ disconnect(): Promise<void>;++ /**+ * Upload binary data to the target virtual path.+ * @param path Virtual path (e.g. "reports/q3.pdf")+ * @param data Binary payload (Buffer, Stream, Uint8Array, Blob, string)+ * @param options Upload options (resumable, mimeType, onProgress)+ */+ upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject>;++ /**+ * Download binary data from the specified virtual path.+ * @param path Virtual path+ */+ download(path: string): Promise<StorageOutput>;++ /**+ * Delete an object at the specified virtual path.+ * @param path Virtual path+ */+ delete(path: string): Promise<void>;++ /**+ * List objects within an optional virtual folder path.+ * @param path Virtual folder path (empty or omitted for root)+ */+ list(path?: string): Promise<StorageObject[]>;++ /**+ * Check if an object exists at the specified virtual path.+ * @param path Virtual path+ */+ exists(path: string): Promise<boolean>;++ /**+ * Retrieve metadata for the object at the virtual path.+ * @param path Virtual path+ */+ metadata(path: string): Promise<StorageObject>;++ // Optional Capability-Dependent Operations+ createFolder?(path: string): Promise<StorageObject>;+ move?(source: string, destination: string): Promise<void>;+ copy?(source: string, destination: string): Promise<void>;+ quota?(): Promise<StorageQuota>;+ backup?(payload: StorageInput, options?: BackupOptions): Promise<StorageObject>;+}diff --git a/packages/core/src/types/storage.ts b/packages/core/src/types/storage.tsnew file mode 100644index 0000000..be31320--- /dev/null+++ b/packages/core/src/types/storage.ts@@ -0,0 +1,93 @@+import type { Readable } from "node:stream";++/**+ * Standard representation of a file or folder in any BYOC storage backend.+ */+export interface StorageObject {+ /** Unique universal identifier (e.g., virtual path or provider ID) */+ readonly id: string;+ /** Normalized virtual path relative to the app root (e.g., "users/123/avatar.jpg") */+ readonly path: string;+ /** Basename of the file or folder (e.g., "avatar.jpg") */+ readonly name: string;+ /** Provider identifier that owns this object (e.g., "google-drive", "cloudflare-r2") */+ readonly provider: string;+ /** Internal provider ID or key (opaque/private reference) */+ readonly providerId: string;++ readonly type?: "file" | "folder";+ readonly size?: number;+ readonly mimeType?: string;+ readonly checksum?: string;+ readonly createdAt?: Date;+ readonly updatedAt?: Date;+ readonly metadata?: Record<string, unknown>;+}++/**+ * Supported binary input types for uploads.+ */+export type StorageInput =+ | Buffer+ | Uint8Array+ | ArrayBuffer+ | Readable+ | ReadableStream+ | Blob+ | string;++/**+ * Standard download output from any provider.+ */+export interface StorageOutput {+ /** Readable binary stream of the content */+ readonly stream: Readable | ReadableStream;+ /** Utility to buffer the entire payload into a Node Buffer (when running in Node) */+ readonly arrayBuffer: () => Promise<ArrayBuffer>;+ /** Utility to read payload as text */+ readonly text: () => Promise<string>;+ /** Metadata of the downloaded object */+ readonly metadata: StorageObject;+}++/**+ * Progress event payload emitted during chunked/resumable uploads.+ */+export interface UploadProgress {+ readonly bytesUploaded: number;+ readonly totalBytes?: number;+ readonly percentage?: number;+}++/**+ * Configuration options for file uploads.+ */+export interface UploadOptions {+ readonly mimeType?: string;+ readonly resumable?: boolean;+ readonly chunkSize?: number;+ readonly onProgress?: (progress: UploadProgress) => void;+ readonly metadata?: Record<string, unknown>;+}++/**+ * Configuration options for automated database/data backups.+ */+export interface BackupOptions {+ readonly filename?: string;+ readonly folder?: string;+ readonly mimeType?: string;+ readonly onProgress?: (progress: UploadProgress) => void;+}++/**+ * Storage quota information reported by the cloud provider.+ */+export interface StorageQuota {+ /** Total storage capacity in bytes (if known) */+ readonly total?: number;+ /** Currently used storage in bytes */+ readonly used: number;+ /** Remaining available storage in bytes (if known) */+ readonly available?: number;+}diff --git a/packages/core/src/utils/logger.ts b/packages/core/src/utils/logger.tsnew file mode 100644index 0000000..9134102--- /dev/null+++ b/packages/core/src/utils/logger.ts@@ -0,0 +1,104 @@+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";++export interface BYOCLogger {+ debug(message: string, ...args: unknown[]): void;+ info(message: string, ...args: unknown[]): void;+ warn(message: string, ...args: unknown[]): void;+ error(message: string, ...args: unknown[]): void;+}++const SENSITIVE_PATTERNS = [+ /Bearer\s+[A-Za-z0-9_\-\.]+/gi,+ /ya29\.[A-Za-z0-9_\-\.]+/gi,+ /("?(?:access_token|refresh_token|client_secret|apiKey|secret|authorization)"?\s*[:=]\s*"?[^",\s}]+"?)/gi+];++/**+ * Recursively sanitizes strings and objects to prevent credential/token leakage.+ */+export function sanitizeLogValue(val: unknown): unknown {+ if (typeof val === "string") {+ let sanitized = val;+ for (const pattern of SENSITIVE_PATTERNS) {+ sanitized = sanitized.replace(pattern, "[REDACTED_SECRET]");+ }+ return sanitized;+ }++ if (val && typeof val === "object") {+ if (Array.isArray(val)) {+ return val.map(sanitizeLogValue);+ }+ if (val instanceof Error) {+ return {+ name: val.name,+ message: sanitizeLogValue(val.message),+ stack: val.stack ? sanitizeLogValue(val.stack) : undefined+ };+ }+ const cleanObj: Record<string, unknown> = {};+ for (const [k, v] of Object.entries(val)) {+ const lowerKey = k.toLowerCase();+ if (+ lowerKey.includes("token") ||+ lowerKey.includes("secret") ||+ lowerKey.includes("password") ||+ lowerKey.includes("authorization")+ ) {+ cleanObj[k] = "[REDACTED_SECRET]";+ } else {+ cleanObj[k] = sanitizeLogValue(v);+ }+ }+ return cleanObj;+ }++ return val;+}++/**+ * SafeLogger — Wraps console logging with zero-token redaction.+ */+export class SafeLogger implements BYOCLogger {+ constructor(private readonly level: LogLevel = "info") {}++ public debug(message: string, ...args: unknown[]): void {+ if (this.shouldLog("debug")) {+ console.debug(`[BYOC DEBUG] ${sanitizeLogValue(message)}`, ...args.map(sanitizeLogValue));+ }+ }++ public info(message: string, ...args: unknown[]): void {+ if (this.shouldLog("info")) {+ console.info(`[BYOC INFO] ${sanitizeLogValue(message)}`, ...args.map(sanitizeLogValue));+ }+ }++ public warn(message: string, ...args: unknown[]): void {+ if (this.shouldLog("warn")) {+ console.warn(`[BYOC WARN] ${sanitizeLogValue(message)}`, ...args.map(sanitizeLogValue));+ }+ }++ public error(message: string, ...args: unknown[]): void {+ if (this.shouldLog("error")) {+ console.error(`[BYOC ERROR] ${sanitizeLogValue(message)}`, ...args.map(sanitizeLogValue));+ }+ }++ private shouldLog(targetLevel: LogLevel): boolean {+ if (this.level === "silent") return false;+ const levels: LogLevel[] = ["debug", "info", "warn", "error"];+ return levels.indexOf(targetLevel) >= levels.indexOf(this.level);+ }+}++/**+ * SilentLogger — Disables all console output.+ */+export class SilentLogger implements BYOCLogger {+ debug(): void {}+ info(): void {}+ warn(): void {}+ error(): void {}+}diff --git a/packages/core/src/utils/mime.ts b/packages/core/src/utils/mime.tsnew file mode 100644index 0000000..7f1711c--- /dev/null+++ b/packages/core/src/utils/mime.ts@@ -0,0 +1,48 @@+import { getBasename } from "../paths/resolver.js";++const MIME_MAP: Record<string, string> = {+ pdf: "application/pdf",+ json: "application/json",+ txt: "text/plain",+ md: "text/markdown",+ csv: "text/csv",+ html: "text/html",+ css: "text/css",+ js: "application/javascript",+ ts: "application/typescript",+ png: "image/png",+ jpg: "image/jpeg",+ jpeg: "image/jpeg",+ gif: "image/gif",+ webp: "image/webp",+ svg: "image/svg+xml",+ mp3: "audio/mpeg",+ wav: "audio/wav",+ ogg: "audio/ogg",+ mp4: "video/mp4",+ webm: "video/webm",+ zip: "application/zip",+ gz: "application/gzip",+ tar: "application/x-tar",+ doc: "application/msword",+ docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",+ xls: "application/vnd.ms-excel",+ xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",+ ppt: "application/vnd.ms-powerpoint",+ pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation"+};++/**+ * Infers standard MIME content-type based on the virtual path extension.+ */+export function lookupMimeType(filePath: string, fallback: string = "application/octet-stream"): string {+ const basename = getBasename(filePath);+ const dotIndex = basename.lastIndexOf(".");++ if (dotIndex === -1 || dotIndex === basename.length - 1) {+ return fallback;+ }++ const ext = basename.slice(dotIndex + 1).toLowerCase();+ return MIME_MAP[ext] || fallback;+}diff --git a/packages/core/src/utils/retry.ts b/packages/core/src/utils/retry.tsnew file mode 100644index 0000000..163c0bf--- /dev/null+++ b/packages/core/src/utils/retry.ts@@ -0,0 +1,60 @@+import { StorageError } from "../errors/storage-error.js";++export interface RetryOptions {+ /** Maximum number of retry attempts (default: 3) */+ maxRetries?: number;+ /** Base delay in milliseconds before the first retry (default: 500ms) */+ baseDelayMs?: number;+ /** Maximum delay cap in milliseconds (default: 10000ms) */+ maxDelayMs?: number;+ /** Custom predicate to determine if an error is retryable */+ shouldRetry?: (error: unknown, attempt: number) => boolean;+}++/**+ * Calculates exponential backoff delay with full randomized jitter.+ * Formula: Math.min(maxDelay, baseDelay * 2^(attempt - 1)) * random(0.5, 1.5)+ */+export function calculateBackoffDelay(+ attempt: number,+ baseDelayMs: number = 500,+ maxDelayMs: number = 10000+): number {+ const exponential = baseDelayMs * Math.pow(2, attempt - 1);+ const capped = Math.min(maxDelayMs, exponential);+ // Full jitter: between 50% and 150% of the calculated exponential delay+ const jitterFactor = 0.5 + Math.random();+ return Math.floor(capped * jitterFactor);+}++/**+ * Executes an async operation with automated exponential backoff and jitter.+ */+export async function withRetry<T>(+ operation: () => Promise<T>,+ options: RetryOptions = {}+): Promise<T> {+ const maxRetries = options.maxRetries ?? 3;+ const baseDelayMs = options.baseDelayMs ?? 500;+ const maxDelayMs = options.maxDelayMs ?? 10000;++ let attempt = 0;++ while (true) {+ attempt++;+ try {+ return await operation();+ } catch (error) {+ const isRetryable =+ options.shouldRetry?.(error, attempt) ??+ (StorageError.isStorageError(error) ? error.retryable : false);++ if (!isRetryable || attempt > maxRetries) {+ throw error;+ }++ const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);+ await new Promise((resolve) => setTimeout(resolve, delay));+ }+ }+}diff --git a/packages/core/tests/client/byoc.test.ts b/packages/core/tests/client/byoc.test.tsnew file mode 100644index 0000000..2b68de5--- /dev/null+++ b/packages/core/tests/client/byoc.test.ts@@ -0,0 +1,218 @@+import { describe, it, expect, vi } from "vitest";+import { BYOC } from "../../src/client/byoc.js";+import type { BYOCProvider, ProviderCapabilities, ProviderManifest } from "../../src/types/provider.js";+import type { StorageObject, StorageOutput, StorageQuota } from "../../src/types/storage.js";+import { BYOCErrorCode } from "../../src/errors/codes.js";+import { StorageError } from "../../src/errors/storage-error.js";++function createMockProvider(overrides: Partial<BYOCProvider> = {}): BYOCProvider {+ const manifest: ProviderManifest = {+ id: "mock-storage",+ name: "Mock Storage",+ category: "self-hosted",+ authentication: "basic",+ supportsUserOwnedStorage: true,+ adapterVersion: "1.0.0"+ };++ const capabilities: ProviderCapabilities = {+ folders: true,+ sharing: false,+ publicUrls: false,+ resumableUploads: true,+ versioning: false,+ quota: true,+ serverSideCopy: false+ };++ return {+ manifest: () => manifest,+ capabilities: () => capabilities,+ connect: vi.fn().mockResolvedValue(undefined),+ disconnect: vi.fn().mockResolvedValue(undefined),+ upload: vi.fn().mockImplementation(async (path: string, _data: any, options?: any) => ({+ id: "mock_id",+ path,+ name: "file.txt",+ provider: manifest.id,+ providerId: "mock_p_id",+ mimeType: options?.mimeType+ })),+ download: vi.fn().mockResolvedValue({+ text: async () => "file content text",+ arrayBuffer: async () => new ArrayBuffer(8),+ metadata: { id: "mock_id", path: "file.txt", name: "file.txt", provider: "mock-storage", providerId: "mock_p_id" }+ } as StorageOutput),+ delete: vi.fn().mockResolvedValue(undefined),+ list: vi.fn().mockResolvedValue([]),+ exists: vi.fn().mockResolvedValue(true),+ metadata: vi.fn().mockImplementation(async (path: string) => ({+ id: "mock_id",+ path,+ name: "file.txt",+ provider: manifest.id,+ providerId: "mock_p_id"+ })),+ createFolder: vi.fn().mockImplementation(async (path: string) => ({+ id: "folder_id",+ path,+ name: "folder",+ provider: manifest.id,+ providerId: "mock_folder_id",+ type: "folder"+ })),+ quota: vi.fn().mockResolvedValue({ total: 1000, used: 100, available: 900 } as StorageQuota),+ ...overrides+ };+}++describe("BYOC Client & Multi-Provider Registry", () => {+ it("throws error if initialized without any provider", () => {+ expect(() => new BYOC({} as any)).toThrowError(StorageError);+ expect(() => new BYOC({ providers: [] } as any)).toThrowError(StorageError);+ });++ it("exposes provider manifest and capability helpers", async () => {+ const provider = createMockProvider();+ const storage = new BYOC({ provider });++ expect(storage.manifest().id).toBe("mock-storage");+ expect(await storage.hasCapability("folders")).toBe(true);+ expect(await storage.hasCapability("publicUrls")).toBe(false);+ });++ it("supports multi-provider registry and dynamic switching", () => {+ const driveProvider = createMockProvider({+ manifest: () => ({+ id: "google-drive",+ name: "Google Drive",+ category: "personal-cloud",+ authentication: "oauth2",+ supportsUserOwnedStorage: true,+ adapterVersion: "1.0.0"+ })+ });++ const s3Provider = createMockProvider({+ manifest: () => ({+ id: "cloudflare-r2",+ name: "Cloudflare R2",+ category: "developer-cloud",+ authentication: "access-key",+ supportsUserOwnedStorage: false,+ adapterVersion: "1.0.0"+ })+ });++ const storage = new BYOC({+ providers: [driveProvider, s3Provider],+ defaultProviderId: "google-drive"+ });++ // 1. Initial provider is Google Drive+ expect(storage.manifest().id).toBe("google-drive");+ expect(storage.getProviders().length).toBe(2);++ // 2. Switch to Cloudflare R2+ storage.useProvider("cloudflare-r2");+ expect(storage.manifest().id).toBe("cloudflare-r2");++ // 3. Switch to unregistered provider throws+ expect(() => storage.useProvider("unknown-provider")).toThrowError(+ expect.objectContaining({ code: BYOCErrorCode.INVALID_INPUT })+ );+ });++ it("supports convenience read/write text and buffer shortcuts", async () => {+ const provider = createMockProvider();+ const storage = new BYOC({ provider });++ // writeText+ const written = await storage.writeText("notes/meeting.md", "# Notes");+ expect(provider.upload).toHaveBeenCalledWith(+ "notes/meeting.md",+ "# Notes",+ expect.objectContaining({ mimeType: "text/markdown" })+ );+ expect(written).toBeDefined();++ // readText+ const text = await storage.readText("notes/meeting.md");+ expect(text).toBe("file content text");++ // readBuffer+ const buffer = await storage.readBuffer("notes/meeting.md");+ expect(buffer).toBeInstanceOf(ArrayBuffer);+ });++ it("normalizes paths before delegating to provider", async () => {+ const provider = createMockProvider();+ const storage = new BYOC({ provider });++ await storage.upload("///documents//report.pdf//", "content");+ expect(provider.upload).toHaveBeenCalledWith("documents/report.pdf", "content", {+ mimeType: "application/pdf"+ });++ await storage.download("\\images\\photo.png");+ expect(provider.download).toHaveBeenCalledWith("images/photo.png");++ await storage.delete(" temp//data.json ");+ expect(provider.delete).toHaveBeenCalledWith("temp/data.json");+ });++ it("throws INVALID_INPUT if empty path is provided to upload or download", async () => {+ const provider = createMockProvider();+ const storage = new BYOC({ provider });++ await expect(storage.upload("", "content")).rejects.toThrowError(StorageError);+ await expect(storage.download(" ")).rejects.toThrowError(StorageError);+ });++ it("throws CAPABILITY_UNSUPPORTED when an unsupported optional method is invoked", async () => {+ const providerWithoutQuota = createMockProvider({+ capabilities: () => ({+ folders: false,+ sharing: false,+ publicUrls: true,+ resumableUploads: true,+ versioning: true,+ quota: false,+ serverSideCopy: true+ }),+ quota: undefined,+ createFolder: undefined+ });++ const storage = new BYOC({ provider: providerWithoutQuota });++ await expect(storage.getQuota()).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED+ })+ );++ await expect(storage.createFolder("new-dir")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.CAPABILITY_UNSUPPORTED+ })+ );+ });++ it("runs backup helper successfully via upload fallback", async () => {+ const provider = createMockProvider({ backup: undefined });+ const storage = new BYOC({ provider });++ const result = await storage.backup(Buffer.from("backup-data"), {+ filename: "db-dump.sql.gz",+ folder: "DatabaseBackups"+ });++ expect(provider.upload).toHaveBeenCalledWith(+ "DatabaseBackups/db-dump.sql.gz",+ expect.any(Buffer),+ expect.objectContaining({ mimeType: "application/gzip" })+ );+ expect(result).toBeDefined();+ });+});diff --git a/packages/core/tests/encryption/e2ee.test.ts b/packages/core/tests/encryption/e2ee.test.tsnew file mode 100644index 0000000..d665570--- /dev/null+++ b/packages/core/tests/encryption/e2ee.test.ts@@ -0,0 +1,245 @@+import crypto from "node:crypto";+import { describe, it, expect } from "vitest";+import { E2EECrypto, EncryptedStorageWrapper } from "../../src/encryption/e2ee.js";+import { BYOCErrorCode } from "../../src/errors/codes.js";+import type { BYOCProvider } from "../../src/types/provider.js";++function createMockProvider(): BYOCProvider {+ const store = new Map<string, Uint8Array>();+ return {+ manifest: () => ({+ id: "mock-backend",+ name: "Mock Cloud",+ category: "developer-cloud",+ authentication: "access-key",+ supportsUserOwnedStorage: true,+ adapterVersion: "0.1.0"+ }),+ capabilities: () => ({+ folders: true,+ sharing: false,+ publicUrls: false,+ resumableUploads: false,+ versioning: false,+ quota: false,+ serverSideCopy: true+ }),+ connect: async () => {},+ disconnect: async () => {},+ upload: async (path, data) => {+ const bytes = Buffer.from(data as any);+ store.set(path, new Uint8Array(bytes));+ return {+ id: `mock_${path}`,+ path,+ name: path,+ provider: "mock-backend",+ providerId: path,+ size: bytes.length+ };+ },+ download: async (path) => {+ const data = store.get(path);+ if (!data) throw new Error("Not found");+ return {+ stream: null as any,+ arrayBuffer: async () => data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer,+ text: async () => new TextDecoder().decode(data),+ metadata: {+ id: `mock_${path}`,+ path,+ name: path,+ provider: "mock-backend",+ providerId: path,+ size: data.length+ }+ };+ },+ delete: async (path) => { store.delete(path); },+ list: async () => [],+ exists: async (path) => store.has(path),+ metadata: async (path) => ({+ id: `mock_${path}`,+ path,+ name: path,+ provider: "mock-backend",+ providerId: path+ })+ };+}++describe("Zero-Knowledge End-to-End Encryption (E2EE)", () => {+ const passphrase = "correct-horse-battery-staple-passphrase-999";++ it("encrypts and decrypts strings and binary buffers roundtrip", async () => {+ const crypto = new E2EECrypto({ passphrase });+ const originalText = "Top Secret Personal Health Record & Banking Info";++ const cipherBytes = await crypto.encrypt(originalText);+ expect(cipherBytes.length).toBeGreaterThan(originalText.length);+ // Ciphertext should not contain plaintext+ expect(new TextDecoder().decode(cipherBytes)).not.toContain("Top Secret");++ const decryptedBytes = await crypto.decrypt(cipherBytes);+ expect(new TextDecoder().decode(decryptedBytes)).toBe(originalText);+ });++ it("transparently supports custom/legacy iteration counts encoded in envelope header", async () => {+ const legacyCrypto = new E2EECrypto({ passphrase, keyDerivationIterations: 20000 });+ const modernCrypto = new E2EECrypto({ passphrase, keyDerivationIterations: 600000 });++ const originalText = "Historical Data Encrypted with 20k Iterations";+ const legacyCipher = await legacyCrypto.encrypt(originalText);++ // Modern client with 600k default seamlessly decrypts 20k file using envelope header+ const decrypted = await modernCrypto.decrypt(legacyCipher);+ expect(new TextDecoder().decode(decrypted)).toBe(originalText);+ });++ it("detects tampering with iteration header count via GCM AAD", async () => {+ const crypto = new E2EECrypto({ passphrase });+ const cipherBytes = await crypto.encrypt("Sensitive Document");++ // Tamper with iteration count byte in header (offset 12..16)+ const tampered = new Uint8Array(cipherBytes);+ tampered[13] = (tampered[13]! + 1) % 256;++ await expect(crypto.decrypt(tampered)).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.AUTH_REQUIRED+ })+ );+ });++ it("rejects an out-of-range iteration count before deriving a key", async () => {+ const crypto = new E2EECrypto({ passphrase });+ const cipherBytes = await crypto.encrypt("Sensitive Document");++ // A hostile but Node-legal work factor (2e9) would cost minutes of PBKDF2+ // on a threadpool thread if it were honoured before the tag check.+ const poisoned = new Uint8Array(cipherBytes);+ const iterBuf = Buffer.alloc(4);+ iterBuf.writeUInt32BE(2_000_000_000, 0);+ poisoned.set(iterBuf, 12);++ const start = Date.now();+ await expect(crypto.decrypt(poisoned)).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.CORRUPTED_DATA+ })+ );+ // Must be rejected up front, not after doing the work.+ expect(Date.now() - start).toBeLessThan(1000);+ });++ it("rejects an iteration count below the minimum work factor", async () => {+ const crypto = new E2EECrypto({ passphrase });+ const cipherBytes = await crypto.encrypt("Sensitive Document");++ const weakened = new Uint8Array(cipherBytes);+ const iterBuf = Buffer.alloc(4);+ iterBuf.writeUInt32BE(1, 0);+ weakened.set(iterBuf, 12);++ await expect(crypto.decrypt(weakened)).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.CORRUPTED_DATA+ })+ );+ });++ it("rejects construction with an out-of-range keyDerivationIterations", () => {+ expect(() => new E2EECrypto({ passphrase, keyDerivationIterations: 100 })).toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.INVALID_INPUT+ })+ );+ });++ it("rejects decryption with an invalid passphrase (tamper-proof)", async () => {+ const cryptoAlice = new E2EECrypto({ passphrase: "alice-correct-password" });+ const cryptoEve = new E2EECrypto({ passphrase: "eve-wrong-password-attacker" });++ const cipherBytes = await cryptoAlice.encrypt("Confidential Document");++ await expect(cryptoEve.decrypt(cipherBytes)).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.AUTH_REQUIRED+ })+ );+ });++ it("transparently supports legacy BYOC_E2EE_V1 envelopes", async () => {+ const modernCrypto = new E2EECrypto({ passphrase });+ const legacyText = "Original File Encrypted with Legacy V1 Envelope";+ const dataBytes = Buffer.from(legacyText, "utf8");+ const salt = crypto.randomBytes(16);+ const iv = crypto.randomBytes(12);++ // Derive with legacy fixed 100k+ const derivedKey = crypto.pbkdf2Sync(Buffer.from(passphrase, "utf8"), salt, 100000, 32, "sha256");+ const cipher = crypto.createCipheriv("aes-256-gcm", derivedKey, iv);+ const aad = Buffer.concat([Buffer.from("BYOC_E2EE_V1"), salt]);+ cipher.setAAD(aad);+ const encrypted = Buffer.concat([cipher.update(dataBytes), cipher.final()]);+ const tag = cipher.getAuthTag();++ const legacyPayload = Buffer.concat([+ Buffer.from("BYOC_E2EE_V1"),+ salt,+ iv,+ tag,+ encrypted+ ]);++ const decrypted = await modernCrypto.decrypt(legacyPayload);+ expect(new TextDecoder().decode(decrypted)).toBe(legacyText);+ });++ it("transparently encrypts on upload and decrypts on download with EncryptedStorageWrapper", async () => {+ const mockCloud = createMockProvider();+ const secureStorage = new EncryptedStorageWrapper(mockCloud, { passphrase });++ await secureStorage.upload("documents/confidential.txt", "Sensitive Patient Records");++ // Verify underlying provider received raw encrypted bytes+ const rawCipher = await mockCloud.download("documents/confidential.txt");+ const rawText = await rawCipher.text();+ expect(rawText).not.toContain("Sensitive Patient Records");+ expect(rawText.startsWith("BYOC_E2EE_V2")).toBe(true);++ // Verify wrapper transparently decrypts+ const decrypted = await secureStorage.download("documents/confidential.txt");+ expect(await decrypted.text()).toBe("Sensitive Patient Records");++ // Verify stream is also plaintext (no ciphertext leak in stream)+ const streamChunks: Buffer[] = [];+ for await (const chunk of decrypted.stream) {+ streamChunks.push(Buffer.from(chunk));+ }+ const streamText = Buffer.concat(streamChunks).toString("utf-8");+ expect(streamText).toBe("Sensitive Patient Records");+ });++ it("forces resumableUploads to false in capabilities", async () => {+ const mockCloud = createMockProvider();+ const secureStorage = new EncryptedStorageWrapper(mockCloud, { passphrase });+ const caps = await secureStorage.capabilities();++ expect(caps.resumableUploads).toBe(false);+ });++ it("encrypts backup payloads before uploading", async () => {+ const mockCloud = createMockProvider();+ const secureStorage = new EncryptedStorageWrapper(mockCloud, { passphrase });++ await secureStorage.backup(JSON.stringify({ secret: "apiKey123" }), {+ filename: "encrypted_backup.json"+ });++ const rawCipher = await mockCloud.download("Backups/encrypted_backup.json");+ const rawText = await rawCipher.text();+ expect(rawText).not.toContain("apiKey123");+ expect(rawText.startsWith("BYOC_E2EE_V2")).toBe(true);+ });+});diff --git a/packages/core/tests/errors/storage-error.test.ts b/packages/core/tests/errors/storage-error.test.tsnew file mode 100644index 0000000..6b605a5--- /dev/null+++ b/packages/core/tests/errors/storage-error.test.ts@@ -0,0 +1,74 @@+import { describe, it, expect } from "vitest";+import { StorageError } from "../../src/errors/storage-error.js";+import { BYOCErrorCode } from "../../src/errors/codes.js";++describe("StorageError", () => {+ it("instantiates properly with all required and optional properties", () => {+ const raw = { originalCode: 429 };+ const err = new StorageError({+ code: BYOCErrorCode.RATE_LIMITED,+ message: "Too many requests to Google Drive",+ provider: "google-drive",+ statusCode: 429,+ retryable: true,+ rawError: raw+ });++ expect(err).toBeInstanceOf(Error);+ expect(err).toBeInstanceOf(StorageError);+ expect(err.name).toBe("StorageError");+ expect(err.code).toBe(BYOCErrorCode.RATE_LIMITED);+ expect(err.message).toBe("Too many requests to Google Drive");+ expect(err.provider).toBe("google-drive");+ expect(err.statusCode).toBe(429);+ expect(err.retryable).toBe(true);+ expect(err.rawError).toBe(raw);+ });++ it("defaults retryable to false if omitted", () => {+ const err = new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: "File not found",+ provider: "google-drive"+ });++ expect(err.retryable).toBe(false);+ });++ it("isStorageError type guard works accurately", () => {+ const storageErr = new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Unauthorized",+ provider: "core"+ });+ const standardErr = new Error("Standard error");+ const plainObject = { code: "BYOC_AUTH_REQUIRED" };++ expect(StorageError.isStorageError(storageErr)).toBe(true);+ expect(StorageError.isStorageError(standardErr)).toBe(false);+ expect(StorageError.isStorageError(plainObject)).toBe(false);+ expect(StorageError.isStorageError(null)).toBe(false);+ });++ it("toJSON serializes cleanly without leaking raw secret objects", () => {+ const err = new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Token expired",+ provider: "google-drive",+ statusCode: 401,+ retryable: false,+ rawError: { sensitiveToken: "SECRET_TOKEN_123" }+ });++ const json = err.toJSON();+ expect(json).toEqual({+ name: "StorageError",+ code: "BYOC_AUTH_REQUIRED",+ message: "Token expired",+ provider: "google-drive",+ statusCode: 401,+ retryable: false+ });+ expect((json as any).rawError).toBeUndefined();+ });+});diff --git a/packages/core/tests/migration/engine.test.ts b/packages/core/tests/migration/engine.test.tsnew file mode 100644index 0000000..de3c2de--- /dev/null+++ b/packages/core/tests/migration/engine.test.ts@@ -0,0 +1,181 @@+import { describe, it, expect, vi } from "vitest";+import { BYOC } from "../../src/client/byoc.js";+import { MigrationEngine } from "../../src/migration/engine.js";+import type { BYOCProvider } from "../../src/types/provider.js";++function createMemoryProvider(id: string, name: string): BYOCProvider {+ const store = new Map<string, { content: string; mimeType?: string }>();++ return {+ manifest: () => ({+ id,+ name,+ category: "self-hosted",+ authentication: "basic",+ supportsUserOwnedStorage: true,+ adapterVersion: "1.0.0"+ }),+ capabilities: () => ({+ folders: true,+ sharing: false,+ publicUrls: false,+ resumableUploads: false,+ versioning: false,+ quota: true,+ serverSideCopy: false+ }),+ connect: async () => {},+ disconnect: async () => {},+ upload: async (path, data, options) => {+ let contentStr = "";+ if (typeof data === "string") {+ contentStr = data;+ } else if (data instanceof ArrayBuffer) {+ contentStr = new TextDecoder().decode(data);+ } else if (data instanceof Uint8Array) {+ contentStr = new TextDecoder().decode(data);+ } else {+ contentStr = String(data);+ }+ store.set(path, { content: contentStr, mimeType: options?.mimeType });+ return { id: `${id}_${path}`, path, name: path, provider: id, providerId: path, size: contentStr.length };+ },+ download: async (path) => {+ const item = store.get(path);+ if (!item) throw new Error(`Not found: ${path}`);+ return {+ stream: null as any,+ text: async () => item.content,+ arrayBuffer: async () => new TextEncoder().encode(item.content).buffer,+ metadata: { id: `${id}_${path}`, path, name: path, provider: id, providerId: path, size: item.content.length, mimeType: item.mimeType }+ };+ },+ delete: async (path) => {+ store.delete(path);+ },+ list: async () => [],+ exists: async (path) => store.has(path),+ metadata: async (path) => {+ const item = store.get(path);+ if (!item) throw new Error(`Not found: ${path}`);+ return { id: `${id}_${path}`, path, name: path, provider: id, providerId: path, size: item.content.length };+ }+ };+}++describe("Universal Migration Engine", () => {+ it("migrates files from source provider to target provider with progress tracking", async () => {+ const source = createMemoryProvider("google-drive", "Google Drive");+ const target = createMemoryProvider("cloudflare-r2", "Cloudflare R2");++ // Populate source files+ await source.upload("users/1/avatar.png", "PNG Data");+ await source.upload("documents/contract.pdf", "PDF Data");+ await source.upload("notes.txt", "Text Data");++ const progressLogs: any[] = [];++ const report = await MigrationEngine.migrate({+ source,+ target,+ paths: ["users/1/avatar.png", "documents/contract.pdf", "notes.txt"],+ conflictStrategy: "overwrite",+ onProgress: (p) => progressLogs.push(p)+ });++ expect(report.filesTotal).toBe(3);+ expect(report.filesMigrated).toBe(3);+ expect(report.filesFailed).toBe(0);+ expect(progressLogs.length).toBe(3);+ expect(progressLogs[2]?.percentage).toBe(100);++ // Verify files now exist on target+ expect(await target.exists("users/1/avatar.png")).toBe(true);+ expect(await target.exists("documents/contract.pdf")).toBe(true);+ expect(await target.exists("notes.txt")).toBe(true);++ const doc = await target.download("documents/contract.pdf");+ expect(await doc.text()).toBe("PDF Data");+ });++ it("orchestrates migration through the BYOC client instance", async () => {+ const drive = createMemoryProvider("google-drive", "Google Drive");+ const nextcloud = createMemoryProvider("webdav", "Nextcloud");++ await drive.upload("database/dump.sql.gz", "SQL GZIP DATA");++ const client = new BYOC({+ providers: [drive, nextcloud]+ });++ const report = await client.migrate({+ from: "google-drive",+ to: "webdav",+ paths: ["database/dump.sql.gz"],+ deleteSourceAfterMigrate: true+ });++ expect(report.filesMigrated).toBe(1);+ expect(await nextcloud.exists("database/dump.sql.gz")).toBe(true);+ // Source was deleted+ expect(await drive.exists("database/dump.sql.gz")).toBe(false);+ });++ it("reports 'partial' without double-counting if source deletion fails", async () => {+ const drive = createMemoryProvider("google-drive", "Google Drive");+ const nextcloud = createMemoryProvider("webdav", "Nextcloud");++ // Make delete throw an error+ drive.delete = async () => {+ throw new Error("Permission Denied: Cannot delete from read-only source");+ };++ await drive.upload("vault/key.pem", "SECRET KEY");++ const report = await MigrationEngine.migrate({+ source: drive,+ target: nextcloud,+ paths: ["vault/key.pem"],+ deleteSourceAfterMigrate: true+ });++ expect(report.filesTotal).toBe(1);+ expect(report.filesMigrated).toBe(0);+ expect(report.filesFailed).toBe(0);+ expect(report.filesPartial).toBe(1);+ // Exactly one record for one input file — no double-counting+ expect(report.results).toHaveLength(1);+ expect(report.results[0]?.status).toBe("partial");+ expect(report.results[0]?.error).toContain("Permission Denied");++ // The whole point of 'partial': the copy really did land on the target+ expect(await nextcloud.exists("vault/key.pem")).toBe(true);+ expect(await (await nextcloud.download("vault/key.pem")).text()).toBe("SECRET KEY");+ // ...and the source copy is still there, awaiting cleanup+ expect(await drive.exists("vault/key.pem")).toBe(true);+ });++ it("still reports 'failed' when the target upload itself fails", async () => {+ const drive = createMemoryProvider("google-drive", "Google Drive");+ const nextcloud = createMemoryProvider("webdav", "Nextcloud");++ nextcloud.upload = async () => {+ throw new Error("Quota Exceeded: target is full");+ };++ await drive.upload("vault/key.pem", "SECRET KEY");++ const report = await MigrationEngine.migrate({+ source: drive,+ target: nextcloud,+ paths: ["vault/key.pem"],+ deleteSourceAfterMigrate: true+ });++ expect(report.filesFailed).toBe(1);+ expect(report.filesPartial).toBe(0);+ expect(report.results[0]?.status).toBe("failed");+ // A real transfer failure must never delete the source+ expect(await drive.exists("vault/key.pem")).toBe(true);+ });+});diff --git a/packages/core/tests/paths/resolver.test.ts b/packages/core/tests/paths/resolver.test.tsnew file mode 100644index 0000000..e68348b--- /dev/null+++ b/packages/core/tests/paths/resolver.test.ts@@ -0,0 +1,87 @@+import { describe, it, expect } from "vitest";+import {+ normalizeVirtualPath,+ getBasename,+ getDirname,+ splitPath+} from "../../src/paths/resolver.js";+import { BYOCErrorCode } from "../../src/errors/codes.js";+import { StorageError } from "../../src/errors/storage-error.js";++describe("Virtual Path Resolver", () => {+ describe("normalizeVirtualPath", () => {+ it("returns empty string for undefined or empty paths", () => {+ expect(normalizeVirtualPath()).toBe("");+ expect(normalizeVirtualPath("")).toBe("");+ expect(normalizeVirtualPath(" ")).toBe("");+ });++ it("normalizes simple paths", () => {+ expect(normalizeVirtualPath("avatar.jpg")).toBe("avatar.jpg");+ expect(normalizeVirtualPath("users/123/avatar.jpg")).toBe("users/123/avatar.jpg");+ });++ it("strips leading and trailing slashes and whitespace", () => {+ expect(normalizeVirtualPath("/users/123/avatar.jpg/")).toBe("users/123/avatar.jpg");+ expect(normalizeVirtualPath(" /documents/report.pdf ")).toBe("documents/report.pdf");+ });++ it("collapses duplicate consecutive slashes", () => {+ expect(normalizeVirtualPath("users///123////avatar.jpg")).toBe("users/123/avatar.jpg");+ expect(normalizeVirtualPath("///a//b///c//")).toBe("a/b/c");+ });++ it("converts Windows backslashes to forward slashes", () => {+ expect(normalizeVirtualPath("users\\123\\avatar.jpg")).toBe("users/123/avatar.jpg");+ expect(normalizeVirtualPath("\\users\\123\\")).toBe("users/123");+ });++ it("ignores current directory dot segments ('.')", () => {+ expect(normalizeVirtualPath("./users/./123/avatar.jpg")).toBe("users/123/avatar.jpg");+ });++ it("throws StorageError with INVALID_INPUT for directory traversal attempts", () => {+ expect(() => normalizeVirtualPath("../secret.txt")).toThrowError(StorageError);++ try {+ normalizeVirtualPath("users/../../etc/passwd");+ } catch (err) {+ expect(StorageError.isStorageError(err)).toBe(true);+ if (StorageError.isStorageError(err)) {+ expect(err.code).toBe(BYOCErrorCode.INVALID_INPUT);+ }+ }+ });++ it("strips NUL bytes and control characters (Bug #8 fix)", () => {+ expect(normalizeVirtualPath("a/bad\u0000name.txt")).toBe("a/badname.txt");+ expect(normalizeVirtualPath("documents/\nreport\r.pdf")).toBe("documents/report.pdf");+ expect(normalizeVirtualPath("\x07system/\x1Fdata.bin")).toBe("system/data.bin");+ });+ });++ describe("getBasename", () => {+ it("returns the filename or last path component", () => {+ expect(getBasename("users/123/avatar.jpg")).toBe("avatar.jpg");+ expect(getBasename("/documents/reports/q3.pdf/")).toBe("q3.pdf");+ expect(getBasename("single_file.txt")).toBe("single_file.txt");+ expect(getBasename("")).toBe("");+ });+ });++ describe("getDirname", () => {+ it("returns the parent directory path", () => {+ expect(getDirname("users/123/avatar.jpg")).toBe("users/123");+ expect(getDirname("avatar.jpg")).toBe("");+ expect(getDirname("/a/b/c/d.txt")).toBe("a/b/c");+ });+ });++ describe("splitPath", () => {+ it("splits path into segments", () => {+ expect(splitPath("users/123/avatar.jpg")).toEqual(["users", "123", "avatar.jpg"]);+ expect(splitPath("avatar.jpg")).toEqual(["avatar.jpg"]);+ expect(splitPath("")).toEqual([]);+ });+ });+});diff --git a/packages/core/tests/spec/conformance.test.ts b/packages/core/tests/spec/conformance.test.tsnew file mode 100644index 0000000..4853ecc--- /dev/null+++ b/packages/core/tests/spec/conformance.test.ts@@ -0,0 +1,144 @@+import { describe, it, expect } from "vitest";+import {+ normalizeVirtualPath,+ getBasename,+ getDirname,+ splitPath,+ rfc3986UriEncode,+ encodePathSegments+} from "../../src/paths/resolver.js";+import { E2EECrypto } from "../../src/encryption/e2ee.js";+import { StorageError } from "../../src/errors/storage-error.js";+import {+ loadFixture,+ type PathNormalizationFixture,+ type PathEncodingFixture,+ type E2EEEnvelopeFixture+} from "./fixtures.js";++/**+ * Cross-SDK conformance suite.+ *+ * Every assertion here comes from /spec/fixtures — the same JSON the Python SDK+ * runs against. If both implementations pass this suite, a file written by one+ * can be read by the other.+ */++describe("Spec conformance: path normalization", () => {+ const fx = loadFixture<PathNormalizationFixture>("path-normalization.json");++ it.each(fx.normalize.cases)("normalize: $name", ({ input, expected }) => {+ const actual = input === null ? normalizeVirtualPath() : normalizeVirtualPath(input);+ expect(actual).toBe(expected);+ });++ it.each(fx.normalize_errors.cases)("rejects: $name", ({ input, error_code }) => {+ try {+ normalizeVirtualPath(input);+ throw new Error(`Expected ${error_code} but no error was thrown`);+ } catch (err) {+ expect(StorageError.isStorageError(err)).toBe(true);+ if (StorageError.isStorageError(err)) expect(err.code).toBe(error_code);+ }+ });++ it.each(fx.basename.cases)("basename($input)", ({ input, expected }) => {+ expect(getBasename(input)).toBe(expected);+ });++ it.each(fx.dirname.cases)("dirname($input)", ({ input, expected }) => {+ expect(getDirname(input)).toBe(expected);+ });++ it.each(fx.split.cases)("split($input)", ({ input, expected }) => {+ expect(splitPath(input)).toEqual(expected);+ });+});++describe("Spec conformance: RFC 3986 path encoding", () => {+ const fx = loadFixture<PathEncodingFixture>("path-encoding.json");++ it.each(fx.rfc3986_uri_encode.cases)(+ "rfc3986UriEncode($input, $encode_slash)",+ ({ input, encode_slash, expected }) => {+ expect(rfc3986UriEncode(input, encode_slash)).toBe(expected);+ }+ );++ it.each(fx.encode_path_segments.cases)("encodePathSegments($input)", ({ input, expected }) => {+ expect(encodePathSegments(input)).toBe(expected);+ });+});++describe("Spec conformance: E2EE envelope", () => {+ const fx = loadFixture<E2EEEnvelopeFixture>("e2ee-envelope.json");++ // Every vector must decrypt to its declared plaintext. This is the assertion+ // that makes encrypted files portable between SDKs.+ it.each(fx.vectors)("decrypts vector: $name", async (vec) => {+ const crypto = new E2EECrypto({ passphrase: vec.passphrase });+ const envelope = Uint8Array.from(Buffer.from(vec.envelope_hex, "hex"));+ const plaintext = await crypto.decrypt(envelope);+ expect(new TextDecoder().decode(plaintext)).toBe(vec.plaintext_utf8);+ });++ // The envelope layout itself is the contract, so assert the byte framing too:+ // a correct plaintext with a wrong layout would still break the other SDK.+ it.each(fx.vectors)("envelope framing matches spec: $name", (vec) => {+ const env = Buffer.from(vec.envelope_hex, "hex");+ const hasIter = vec.version === "V2";+ let offset = 0;++ expect(env.subarray(offset, offset + 12).toString()).toBe(`BYOC_E2EE_${vec.version}`);+ offset += 12;++ if (hasIter) {+ expect(env.subarray(offset, offset + 4).readUInt32BE(0)).toBe(vec.iterations);+ offset += 4;+ }++ expect(env.subarray(offset, offset + 16).toString("hex")).toBe(vec.salt_hex);+ offset += 16;+ expect(env.subarray(offset, offset + 12).toString("hex")).toBe(vec.iv_hex);+ offset += 12;+ expect(env.subarray(offset, offset + 16).toString("hex")).toBe(vec.tag_hex);+ offset += 16;+ expect(env.subarray(offset).toString("hex")).toBe(vec.ciphertext_hex);+ });++ it("round-trips its own output through the declared bounds", async () => {+ const crypto = new E2EECrypto({ passphrase: "spec-conformance-passphrase" });+ const envelope = await crypto.encrypt("round trip");+ expect(Buffer.from(envelope.subarray(0, 12)).toString()).toBe("BYOC_E2EE_V2");+ const iterations = Buffer.from(envelope.subarray(12, 16)).readUInt32BE(0);+ expect(iterations).toBeGreaterThanOrEqual(fx.iteration_bounds.min);+ expect(iterations).toBeLessThanOrEqual(fx.iteration_bounds.max);+ expect(new TextDecoder().decode(await crypto.decrypt(envelope))).toBe("round trip");+ });++ it.each(fx.rejection_cases)("rejects: $name", async (rc) => {+ const vec = fx.vectors.find((v) => v.version === "V2")!;+ let env = Buffer.from(vec.envelope_hex, "hex");++ if (rc.mutate) {+ env = Buffer.from(env);+ if (rc.mutate.uint32_be !== undefined) {+ env.writeUInt32BE(rc.mutate.uint32_be, rc.mutate.offset);+ }+ if (rc.mutate.ascii !== undefined) {+ Buffer.from(rc.mutate.ascii).copy(env, rc.mutate.offset);+ }+ }+ if (rc.truncate_to !== undefined) {+ env = env.subarray(0, rc.truncate_to);+ }++ const crypto = new E2EECrypto({ passphrase: rc.passphrase ?? vec.passphrase });+ const started = Date.now();+ await expect(crypto.decrypt(Uint8Array.from(env))).rejects.toThrowError(+ expect.objectContaining({ code: rc.expect_error })+ );+ // An out-of-range work factor must be refused before any key derivation runs.+ expect(Date.now() - started).toBeLessThan(2000);+ });+});diff --git a/packages/core/tests/spec/fixtures.ts b/packages/core/tests/spec/fixtures.tsnew file mode 100644index 0000000..925fe1f--- /dev/null+++ b/packages/core/tests/spec/fixtures.ts@@ -0,0 +1,59 @@+import { readFileSync } from "node:fs";+import { fileURLToPath } from "node:url";+import { dirname, resolve } from "node:path";++/**+ * Loader for the shared cross-SDK conformance fixtures in /spec/fixtures.+ *+ * These files are the contract between BYOC SDK implementations. Every language+ * binding runs against the same JSON, so a fixture failure here means the+ * TypeScript SDK has drifted from the spec — fix the implementation, not the+ * fixture.+ */+const FIXTURE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../spec/fixtures");++export function loadFixture<T>(name: string): T {+ return JSON.parse(readFileSync(resolve(FIXTURE_DIR, name), "utf8")) as T;+}++export interface PathNormalizationFixture {+ version: number;+ normalize: { cases: Array<{ name: string; input: string | null; expected: string }> };+ normalize_errors: { cases: Array<{ name: string; input: string; error_code: string }> };+ basename: { cases: Array<{ input: string; expected: string }> };+ dirname: { cases: Array<{ input: string; expected: string }> };+ split: { cases: Array<{ input: string; expected: string[] }> };+}++export interface PathEncodingFixture {+ version: number;+ rfc3986_uri_encode: {+ cases: Array<{ input: string; encode_slash: boolean; expected: string }>;+ };+ encode_path_segments: { cases: Array<{ input: string; expected: string }> };+}++export interface E2EEEnvelopeFixture {+ version: number;+ iteration_bounds: { min: number; max: number };+ vectors: Array<{+ name: string;+ version: string;+ passphrase: string;+ iterations: number;+ salt_hex: string;+ iv_hex: string;+ plaintext_utf8: string;+ derived_key_hex: string;+ tag_hex: string;+ ciphertext_hex: string;+ envelope_hex: string;+ }>;+ rejection_cases: Array<{+ name: string;+ mutate?: { offset: number; uint32_be?: number; ascii?: string };+ passphrase?: string;+ truncate_to?: number;+ expect_error: string;+ }>;+}diff --git a/packages/core/tests/utils/logger.test.ts b/packages/core/tests/utils/logger.test.tsnew file mode 100644index 0000000..d3a6371--- /dev/null+++ b/packages/core/tests/utils/logger.test.ts@@ -0,0 +1,55 @@+import { describe, it, expect, vi } from "vitest";+import { SafeLogger, SilentLogger, sanitizeLogValue } from "../../src/utils/logger.js";++describe("SafeLogger & Secret Redaction", () => {+ it("redacts Bearer tokens and Google ya29 tokens in strings", () => {+ const rawMsg = "Connecting with Bearer ya29.a0AfH6SMAxyz123 to Google Drive";+ const clean = sanitizeLogValue(rawMsg) as string;++ expect(clean).not.toContain("ya29");+ expect(clean).not.toContain("ya29.a0AfH6SMAxyz123");+ expect(clean).toContain("[REDACTED_SECRET]");+ });++ it("redacts sensitive fields in nested objects", () => {+ const payload = {+ user: "alice",+ auth: {+ accessToken: "secret-token-abc",+ refreshToken: "secret-refresh-xyz",+ clientSecret: "top-secret-val"+ },+ file: "report.pdf"+ };++ const sanitized = sanitizeLogValue(payload) as any;+ expect(sanitized.user).toBe("alice");+ expect(sanitized.file).toBe("report.pdf");+ expect(sanitized.auth.accessToken).toBe("[REDACTED_SECRET]");+ expect(sanitized.auth.refreshToken).toBe("[REDACTED_SECRET]");+ expect(sanitized.auth.clientSecret).toBe("[REDACTED_SECRET]");+ });++ it("SafeLogger outputs scrubbed messages to console methods", () => {+ const infoSpy = vi.spyOn(console, "info").mockImplementation(() => {});++ const logger = new SafeLogger("info");+ logger.info("Upload with token ya29.a0AfH6SMAxyz");++ expect(infoSpy).toHaveBeenCalledWith(+ expect.stringContaining("[BYOC INFO] Upload with token [REDACTED_SECRET]")+ );++ infoSpy.mockRestore();+ });++ it("SilentLogger suppresses all logs", () => {+ const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});++ const logger = new SilentLogger();+ logger.error("Something went wrong");++ expect(errorSpy).not.toHaveBeenCalled();+ errorSpy.mockRestore();+ });+});diff --git a/packages/core/tests/utils/mime.test.ts b/packages/core/tests/utils/mime.test.tsnew file mode 100644index 0000000..26a6710--- /dev/null+++ b/packages/core/tests/utils/mime.test.ts@@ -0,0 +1,25 @@+import { describe, it, expect } from "vitest";+import { lookupMimeType } from "../../src/utils/mime.js";++describe("MIME Lookup Utility", () => {+ it("maps standard file extensions to proper MIME types", () => {+ expect(lookupMimeType("document.pdf")).toBe("application/pdf");+ expect(lookupMimeType("photos/avatar.png")).toBe("image/png");+ expect(lookupMimeType("photos/picture.jpeg")).toBe("image/jpeg");+ expect(lookupMimeType("data/stats.json")).toBe("application/json");+ expect(lookupMimeType("data/table.csv")).toBe("text/csv");+ expect(lookupMimeType("archive/backup.sql.gz")).toBe("application/gzip");+ expect(lookupMimeType("videos/lecture.mp4")).toBe("video/mp4");+ });++ it("handles case-insensitive extensions", () => {+ expect(lookupMimeType("PHOTO.JPG")).toBe("image/jpeg");+ expect(lookupMimeType("REPORT.PDF")).toBe("application/pdf");+ });++ it("falls back to application/octet-stream for unknown extensions or missing extensions", () => {+ expect(lookupMimeType("file-without-extension")).toBe("application/octet-stream");+ expect(lookupMimeType("file.unknownextension123")).toBe("application/octet-stream");+ expect(lookupMimeType("file.custom", "text/plain")).toBe("text/plain");+ });+});diff --git a/packages/core/tests/utils/retry.test.ts b/packages/core/tests/utils/retry.test.tsnew file mode 100644index 0000000..bc42548--- /dev/null+++ b/packages/core/tests/utils/retry.test.ts@@ -0,0 +1,96 @@+import { describe, it, expect, vi } from "vitest";+import { withRetry, calculateBackoffDelay } from "../../src/utils/retry.js";+import { StorageError } from "../../src/errors/storage-error.js";+import { BYOCErrorCode } from "../../src/errors/codes.js";++describe("Retry Utility", () => {+ describe("calculateBackoffDelay", () => {+ it("scales delay with exponential attempts and stays within jitter range", () => {+ const delay1 = calculateBackoffDelay(1, 100, 10000);+ expect(delay1).toBeGreaterThanOrEqual(50); // 100 * 0.5+ expect(delay1).toBeLessThanOrEqual(150); // 100 * 1.5++ const delay3 = calculateBackoffDelay(3, 100, 10000);+ expect(delay3).toBeGreaterThanOrEqual(200); // 400 * 0.5+ expect(delay3).toBeLessThanOrEqual(600); // 400 * 1.5+ });++ it("respects maxDelay cap", () => {+ const delayCapped = calculateBackoffDelay(10, 1000, 2000);+ expect(delayCapped).toBeLessThanOrEqual(3000); // 2000 * 1.5 max jitter+ });+ });++ describe("withRetry", () => {+ it("returns result immediately on successful execution without retry", async () => {+ const op = vi.fn().mockResolvedValue("success");+ const result = await withRetry(op);+ expect(result).toBe("success");+ expect(op).toHaveBeenCalledTimes(1);+ });++ it("retries on retryable StorageError up to maxRetries", async () => {+ const retryableError = new StorageError({+ code: BYOCErrorCode.RATE_LIMITED,+ message: "Throttled",+ provider: "mock",+ retryable: true+ });++ const op = vi+ .fn()+ .mockRejectedValueOnce(retryableError)+ .mockRejectedValueOnce(retryableError)+ .mockResolvedValue("eventual success");++ const result = await withRetry(op, {+ maxRetries: 3,+ baseDelayMs: 5,+ maxDelayMs: 20+ });++ expect(result).toBe("eventual success");+ expect(op).toHaveBeenCalledTimes(3);+ });++ it("fails immediately on non-retryable StorageError without retrying", async () => {+ const nonRetryableError = new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Invalid token",+ provider: "mock",+ retryable: false+ });++ const op = vi.fn().mockRejectedValue(nonRetryableError);++ await expect(+ withRetry(op, {+ maxRetries: 3,+ baseDelayMs: 5+ })+ ).rejects.toThrow(nonRetryableError);++ expect(op).toHaveBeenCalledTimes(1);+ });++ it("throws after exhausting maxRetries", async () => {+ const retryableError = new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: "Backend 503",+ provider: "mock",+ retryable: true+ });++ const op = vi.fn().mockRejectedValue(retryableError);++ await expect(+ withRetry(op, {+ maxRetries: 2,+ baseDelayMs: 5+ })+ ).rejects.toThrow(retryableError);++ expect(op).toHaveBeenCalledTimes(3); // Initial attempt + 2 retries+ });+ });+});diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.jsonnew file mode 100644index 0000000..b1873a0--- /dev/null+++ b/packages/core/tsconfig.json@@ -0,0 +1,9 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": "src",+ "outDir": "dist",+ "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"+ },+ "include": ["src/**/*"]+}diff --git a/packages/google-drive/LICENSE b/packages/google-drive/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/packages/google-drive/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/packages/google-drive/README.md b/packages/google-drive/README.mdnew file mode 100644index 0000000..4e97e0c--- /dev/null+++ b/packages/google-drive/README.md@@ -0,0 +1,81 @@+# @byoc/google-drive++Google Drive provider adapter for **BYOC (Bring Your Own Cloud)**: keep application files in the Drive account the end user already owns.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Requires `@byoc/core`.+>+> **Status: v0.2.0.** Unit tested, and validated against the live Google Drive API.++## Install++```bash+npm install @byoc/core @byoc/google-drive+```++## Setup++You need a Google Cloud OAuth client before any of this works. [**Google Drive OAuth Setup**](../../docs/google-oauth-setup.md) covers it end to end, including the console's silent-failure spots.++## OAuth 2.0 with PKCE++This adapter uses the non-restricted `drive.file` scope, so an application never needs a Google Restricted Scope Security Assessment. It can only see files it created or that the user explicitly opened with it.++```ts+import { BYOC } from "@byoc/core";+import {+ GoogleDriveProvider,+ GoogleDriveScope,+ generateCodeVerifier,+ generateCodeChallenge,+ generateOAuthState+} from "@byoc/google-drive";++const codeVerifier = generateCodeVerifier(64);+const codeChallenge = await generateCodeChallenge(codeVerifier);+const state = generateOAuthState(32);++const gdrive = new GoogleDriveProvider({+ auth: {+ clientId: process.env.GOOGLE_CLIENT_ID!,+ redirectUri: "https://myapp.com/api/auth/callback",+ scopes: [GoogleDriveScope.FILE]+ },+ rootFolderName: "MyApplication"+});++// Redirect the user here, then handle the callback:+const loginUrl = gdrive.oauth.getAuthorizationUrl({ state, codeChallenge });+await gdrive.oauth.exchangeCode({ code, codeVerifier });++const storage = new BYOC({ provider: gdrive });+await storage.connect();+await storage.writeText("notes/meeting.md", "# Q3 Strategy Notes");+```++## Persisting refresh tokens++The default `InMemoryTokenStorage` clears on restart. For long-lived sessions use `EncryptedFileTokenStorage`, which persists tokens with AES-256-GCM:++```ts+import { EncryptedFileTokenStorage } from "@byoc/google-drive";++const gdrive = new GoogleDriveProvider({+ auth: { clientId: process.env.GOOGLE_CLIENT_ID! },+ tokenStorage: new EncryptedFileTokenStorage({+ filePath: "./.byoc-session.enc",+ encryptionKey: process.env.TOKEN_ENCRYPTION_KEY!+ })+});+```++## What this adapter handles++- **Virtual POSIX paths**: `users/123/report.pdf` is resolved to Drive's opaque file IDs, with nested folders created on demand.+- **404 self-healing**: if a user renames or deletes a file in the Drive web UI, the stale cache entry is invalidated and the path re-resolved.+- **Resumable uploads**: multi-gigabyte files in 256 KiB-aligned chunks with `onProgress` callbacks and network-failure resumption.+- **Query escaping**: filenames containing `'` or `\` are escaped per the Drive API v3 spec.+- **Rate limiting**: 429 and 5xx responses retried with exponential backoff.++## License++[Apache-2.0](./LICENSE)diff --git a/packages/google-drive/package.json b/packages/google-drive/package.jsonnew file mode 100644index 0000000..f898367--- /dev/null+++ b/packages/google-drive/package.json@@ -0,0 +1,55 @@+{+ "name": "@byoc/google-drive",+ "version": "0.2.1",+ "description": "Google Drive storage provider adapter for BYOC (Bring Your Own Cloud)",+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js",+ "default": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "!dist/tsconfig.tsbuildinfo",+ "README.md",+ "LICENSE"+ ],+ "scripts": {+ "build": "tsc -b",+ "clean": "rm -rf dist tsconfig.tsbuildinfo"+ },+ "dependencies": {+ "@byoc/core": "^0.2.1",+ "@types/node": ">=20"+ },+ "keywords": [+ "byoc",+ "google-drive",+ "cloud-storage",+ "adapter",+ "oauth2",+ "pkce"+ ],+ "author": "Ajay Ramineni",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Ajayvarmaramineni/BYOC.git",+ "directory": "packages/google-drive"+ },+ "publishConfig": {+ "access": "public"+ },+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC/tree/main/packages/google-drive#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ },+ "sideEffects": false+}diff --git a/packages/google-drive/src/adapter.ts b/packages/google-drive/src/adapter.tsnew file mode 100644index 0000000..414ed7f--- /dev/null+++ b/packages/google-drive/src/adapter.ts@@ -0,0 +1,347 @@+import type {+ BYOCProvider,+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+ BackupOptions+} from "@byoc/core";+import {+ BYOCErrorCode,+ StorageError,+ normalizeVirtualPath,+ getBasename+} from "@byoc/core";+import type { GoogleDriveProviderConfig } from "./auth/types.js";+import { GoogleOAuthClient } from "./auth/oauth-client.js";+import { DriveHttpClient } from "./api/http.js";+import {+ GoogleDrivePathResolver,+ LruTtlPathCache,+ type PathCache+} from "./paths/virtual-path.js";++import { ResumableUploader } from "./api/resumable.js";+import { buildMultipartBody } from "./api/multipart.js";++/**+ * GoogleDriveProvider — Official reference adapter for Google Drive.+ */+export class GoogleDriveProvider implements BYOCProvider {+ public readonly config: GoogleDriveProviderConfig;+ public readonly oauth: GoogleOAuthClient;+ public readonly http: DriveHttpClient;+ public readonly uploader: ResumableUploader;+ public readonly resolver: GoogleDrivePathResolver;++ constructor(+ config: GoogleDriveProviderConfig,+ options?: { pathCache?: PathCache }+ ) {+ if (!config || !config.auth || !config.auth.clientId) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "GoogleDriveProvider requires a valid 'auth.clientId'.",+ provider: "google-drive",+ retryable: false+ });+ }++ this.config = {+ ...config,+ rootFolderName: config.rootFolderName ?? "BYOC"+ };++ this.oauth = new GoogleOAuthClient(config.auth);+ this.http = new DriveHttpClient(this.oauth);+ this.uploader = new ResumableUploader(this.oauth);+ const cache = options?.pathCache ?? new LruTtlPathCache();+ this.resolver = new GoogleDrivePathResolver(this.http, this.config.rootFolderName, cache);+ }++ /**+ * Manifest identifying this provider to the BYOC runtime.+ */+ public manifest(): ProviderManifest {+ return {+ id: "google-drive",+ name: "Google Drive",+ category: "personal-cloud",+ authentication: "oauth2",+ supportsUserOwnedStorage: true,+ adapterVersion: "0.2.0"+ };+ }++ /**+ * Declares the capabilities supported by Google Drive.+ */+ public capabilities(): ProviderCapabilities {+ return {+ folders: true,+ sharing: true,+ publicUrls: false,+ resumableUploads: true,+ versioning: false,+ quota: true,+ serverSideCopy: true+ };+ }++ /**+ * Initialize and verify OAuth connection session, ensuring the root app folder exists.+ */+ public async connect(): Promise<void> {+ const hasSession = await this.oauth.hasValidSession();+ if (!hasSession) {+ throw new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Google Drive authentication required: No valid session found. Please complete OAuth flow.",+ provider: "google-drive",+ statusCode: 401,+ retryable: false+ });+ }++ // Verify token validity by resolving root folder+ await this.resolver.ensureRootFolder();+ }++ /**+ * Disconnect and clear local token/cache sessions, revoking active credentials.+ */+ public async disconnect(): Promise<void> {+ await this.oauth.revoke();+ await this.resolver.clearCache();+ }++ /**+ * Uploads a file to Google Drive (using multipart for small files, resumable for large files).+ */+ public async upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ const filename = getBasename(normalized);+ const parentFolderId = await this.resolver.resolveParentFolderId(normalized);++ const metadata = {+ name: filename,+ parents: [parentFolderId],+ mimeType: options?.mimeType,+ appProperties: {+ byocVirtualPath: normalized,+ ...((options?.metadata as Record<string, string>) || {})+ }+ };++ // Determine if resumable upload is appropriate (explicit flag, onProgress listener, or large byte length)+ const byteLength =+ typeof data === "string"+ ? Buffer.byteLength(data)+ : data instanceof Uint8Array || (typeof Buffer !== "undefined" && Buffer.isBuffer(data))+ ? data.byteLength+ : undefined;++ const isLarge = byteLength !== undefined && byteLength >= 5 * 1024 * 1024; // 5 MB threshold+ const shouldUseResumable = options?.resumable || options?.onProgress || isLarge;++ let resource;+ if (shouldUseResumable) {+ resource = await this.uploader.upload(metadata, data, {+ mimeType: options?.mimeType,+ chunkSize: options?.chunkSize,+ onProgress: options?.onProgress+ });+ } else {+ const multipart = await buildMultipartBody(metadata, data, options?.mimeType);+ const boundaryMatch = multipart.contentType.match(/boundary=(.+)$/);+ const boundary = boundaryMatch ? boundaryMatch[1]! : `BYOC_${Date.now()}`;+ resource = await this.http.uploadMultipart(boundary, multipart.body);+ }++ // Cache the resolved file ID+ await this.resolver.setCached(normalized, resource.id);++ return this.http.toStorageObject(resource, normalized);+ }++ /**+ * Downloads a file from Google Drive with 404 cache self-healing.+ */+ public async download(path: string): Promise<StorageOutput> {+ const normalized = normalizeVirtualPath(path);++ try {+ const fileId = await this.resolver.resolveFileId(normalized);+ const resource = await this.http.getFile(fileId);+ const media = await this.http.downloadMedia(fileId);++ return {+ stream: media.stream,+ arrayBuffer: media.arrayBuffer,+ text: media.text,+ metadata: this.http.toStorageObject(resource, normalized)+ };+ } catch (err) {+ // If 404 occurs on cached ID, invalidate cache and retry once+ if (StorageError.isStorageError(err) && err.code === BYOCErrorCode.OBJECT_NOT_FOUND) {+ await this.resolver.invalidate(normalized);+ const freshFileId = await this.resolver.resolveFileId(normalized, { skipCache: true });+ const resource = await this.http.getFile(freshFileId);+ const media = await this.http.downloadMedia(freshFileId);++ return {+ stream: media.stream,+ arrayBuffer: media.arrayBuffer,+ text: media.text,+ metadata: this.http.toStorageObject(resource, normalized)+ };+ }+ throw err;+ }+ }++ /**+ * Deletes an object from Google Drive with cache invalidation.+ * If softDelete option is specified, moves the file to Google Drive Trash.+ */+ public async delete(path: string, options?: { softDelete?: boolean }): Promise<void> {+ const normalized = normalizeVirtualPath(path);+ const fileId = await this.resolver.resolveFileId(normalized);+ if (options?.softDelete) {+ await this.http.trashFile(fileId);+ } else {+ await this.http.deleteFile(fileId);+ }+ await this.resolver.invalidate(normalized);+ }++ /**+ * Server-side instant copy in Google Drive using files.copy without re-uploading bytes.+ */+ public async copy(source: string, destination: string): Promise<void> {+ const sourceNorm = normalizeVirtualPath(source);+ const destNorm = normalizeVirtualPath(destination);++ const sourceFileId = await this.resolver.resolveFileId(sourceNorm);+ const destParentId = await this.resolver.resolveParentFolderId(destNorm);+ const newFilename = getBasename(destNorm);++ const copied = await this.http.copyFile(sourceFileId, newFilename, destParentId);+ await this.resolver.setCached(destNorm, copied.id);+ }++ /**+ * Server-side instant move in Google Drive using files.update (parent swapping) without re-uploading bytes.+ */+ public async move(source: string, destination: string): Promise<void> {+ const sourceNorm = normalizeVirtualPath(source);+ const destNorm = normalizeVirtualPath(destination);++ const sourceFileId = await this.resolver.resolveFileId(sourceNorm);+ const oldParentId = await this.resolver.resolveParentFolderId(sourceNorm);+ const newParentId = await this.resolver.resolveParentFolderId(destNorm);+ const newFilename = getBasename(destNorm);++ await this.http.moveFile(sourceFileId, newParentId, oldParentId, newFilename);+ await this.resolver.invalidate(sourceNorm);+ await this.resolver.setCached(destNorm, sourceFileId);+ }++ /**+ * Lists files and folders within a path.+ */+ public async list(path?: string): Promise<StorageObject[]> {+ const normalized = normalizeVirtualPath(path);+ const parentId = normalized+ ? await this.resolver.resolveFileId(normalized)+ : await this.resolver.ensureRootFolder();++ const query = `'${parentId}' in parents and trashed = false`;+ const response = await this.http.listFiles(query);++ return response.files.map((file) => {+ const childPath = normalized ? `${normalized}/${file.name}` : file.name;+ return this.http.toStorageObject(file, childPath);+ });+ }++ /**+ * Checks if an object exists in Google Drive.+ */+ public async exists(path: string): Promise<boolean> {+ const normalized = normalizeVirtualPath(path);+ if (!normalized) return true;++ try {+ await this.resolver.resolveFileId(normalized);+ return true;+ } catch (err) {+ if (StorageError.isStorageError(err) && err.code === BYOCErrorCode.OBJECT_NOT_FOUND) {+ return false;+ }+ throw err;+ }+ }++ /**+ * Retrieves metadata for an object in Google Drive.+ */+ public async metadata(path: string): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ const fileId = await this.resolver.resolveFileId(normalized);+ const resource = await this.http.getFile(fileId);+ return this.http.toStorageObject(resource, normalized);+ }++ /**+ * Creates a virtual folder in Google Drive.+ */+ public async createFolder(path: string): Promise<StorageObject> {+ const normalized = normalizeVirtualPath(path);+ const folderId = await this.resolver.resolveOrCreateFolderPath(normalized);+ const resource = await this.http.getFile(folderId);+ return this.http.toStorageObject(resource, normalized);+ }++ /**+ * Retrieves user storage quota from Google Drive.+ */+ public async quota(): Promise<StorageQuota> {+ const about = await this.http.getAboutQuota();+ const quotaData = about.storageQuota;++ return {+ total: quotaData?.limit ? Number(quotaData.limit) : undefined,+ used: quotaData?.usage ? Number(quotaData.usage) : 0,+ available:+ quotaData?.limit && quotaData.usage+ ? Math.max(0, Number(quotaData.limit) - Number(quotaData.usage))+ : undefined+ };+ }++ /**+ * Specialized backup helper.+ */+ public async backup(+ payload: StorageInput,+ options?: BackupOptions+ ): Promise<StorageObject> {+ const folder = normalizeVirtualPath(options?.folder ?? "Backups");+ const filename =+ options?.filename ?? `backup-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;+ const targetPath = folder ? `${folder}/${filename}` : filename;++ return this.upload(targetPath, payload, {+ mimeType: options?.mimeType ?? "application/json",+ onProgress: options?.onProgress+ });+ }+}diff --git a/packages/google-drive/src/api/http.ts b/packages/google-drive/src/api/http.tsnew file mode 100644index 0000000..225a4e0--- /dev/null+++ b/packages/google-drive/src/api/http.ts@@ -0,0 +1,289 @@+import { withRetry, type StorageObject } from "@byoc/core";+import { GoogleOAuthClient } from "../auth/oauth-client.js";+import { mapGoogleDriveError } from "../errors/mapper.js";+import type {+ DriveFileResource,+ DriveFileListResponse,+ DriveAboutResource+} from "./types.js";+import { Readable } from "node:stream";++export const DRIVE_API_BASE = "https://www.googleapis.com/drive/v3";+export const DRIVE_UPLOAD_BASE = "https://www.googleapis.com/upload/drive/v3";++/**+ * DriveHttpClient — Handles low-level authenticated REST requests to the Google Drive API v3.+ */+export class DriveHttpClient {+ constructor(public readonly oauth: GoogleOAuthClient) {}++ /**+ * Executes an authenticated JSON request with automatic exponential backoff.+ */+ public async request<T>(+ url: string,+ options: RequestInit = {}+ ): Promise<T> {+ return withRetry(async () => {+ const accessToken = await this.oauth.getAccessToken();+ const headers = new Headers(options.headers || {});+ headers.set("Authorization", `Bearer ${accessToken}`);++ const response = await fetch(url, {+ ...options,+ headers+ });++ if (!response.ok) {+ let errorData: unknown;+ try {+ errorData = await response.json();+ } catch {+ errorData = await response.text();+ }+ throw mapGoogleDriveError({ status: response.status, data: errorData });+ }++ if (response.status === 204) {+ return undefined as unknown as T;+ }++ return (await response.json()) as T;+ }, {+ maxRetries: 3,+ baseDelayMs: 500+ });+ }++ /**+ * Performs a multipart upload (metadata + media) in a single HTTP request.+ */+ public async uploadMultipart(+ boundary: string,+ body: Uint8Array+ ): Promise<DriveFileResource> {+ const url = `${DRIVE_UPLOAD_BASE}/files?uploadType=multipart&fields=id,name,mimeType,size,parents,createdTime,modifiedTime,md5Checksum,trashed`;++ return withRetry(async () => {+ const accessToken = await this.oauth.getAccessToken();+ const response = await fetch(url, {+ method: "POST",+ headers: {+ Authorization: `Bearer ${accessToken}`,+ "Content-Type": `multipart/related; boundary=${boundary}`,+ "Content-Length": String(body.byteLength)+ },+ body: body as any+ });++ if (!response.ok) {+ let errorData: unknown;+ try {+ errorData = await response.json();+ } catch {+ errorData = await response.text();+ }+ throw mapGoogleDriveError({ status: response.status, data: errorData });+ }++ return (await response.json()) as DriveFileResource;+ }, {+ maxRetries: 3,+ baseDelayMs: 500+ });+ }++ /**+ * Downloads the raw binary media for a file ID.+ */+ public async downloadMedia(fileId: string): Promise<{+ stream: Readable | ReadableStream;+ arrayBuffer: () => Promise<ArrayBuffer>;+ text: () => Promise<string>;+ }> {+ const url = `${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}?alt=media`;++ return withRetry(async () => {+ const accessToken = await this.oauth.getAccessToken();+ const response = await fetch(url, {+ method: "GET",+ headers: {+ Authorization: `Bearer ${accessToken}`+ }+ });++ if (!response.ok) {+ let errorData: unknown;+ try {+ errorData = await response.json();+ } catch {+ errorData = await response.text();+ }+ throw mapGoogleDriveError({ status: response.status, data: errorData });+ }++ const stream = (response.body ?? Readable.from([])) as any;++ return {+ stream,+ arrayBuffer: async () => response.arrayBuffer(),+ text: async () => response.text()+ };+ }, {+ maxRetries: 3,+ baseDelayMs: 500+ });+ }++ /**+ * Retrieves metadata for a file ID.+ */+ public async getFile(fileId: string): Promise<DriveFileResource> {+ const url = `${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}?fields=id,name,mimeType,size,parents,createdTime,modifiedTime,md5Checksum,trashed,appProperties`;+ return this.request<DriveFileResource>(url, { method: "GET" });+ }++ /**+ * Queries files matching a Drive query string.+ */+ public async listFiles(+ query?: string,+ pageSize: number = 100,+ pageToken?: string+ ): Promise<DriveFileListResponse> {+ const url = new URL(`${DRIVE_API_BASE}/files`);+ url.searchParams.set("pageSize", String(pageSize));+ url.searchParams.set(+ "fields",+ "nextPageToken,files(id,name,mimeType,size,parents,createdTime,modifiedTime,md5Checksum,trashed,appProperties)"+ );++ if (query) {+ url.searchParams.set("q", query);+ }+ if (pageToken) {+ url.searchParams.set("pageToken", pageToken);+ }++ return this.request<DriveFileListResponse>(url.toString(), { method: "GET" });+ }++ /**+ * Creates a folder node in Google Drive.+ */+ public async createFolder(name: string, parentId?: string): Promise<DriveFileResource> {+ const url = `${DRIVE_API_BASE}/files?fields=id,name,mimeType,parents,createdTime,modifiedTime`;+ const metadata: Record<string, unknown> = {+ name,+ mimeType: "application/vnd.google-apps.folder"+ };++ if (parentId) {+ metadata.parents = [parentId];+ }++ return this.request<DriveFileResource>(url, {+ method: "POST",+ headers: {+ "Content-Type": "application/json"+ },+ body: JSON.stringify(metadata)+ });+ }++ /**+ * Copies a file server-side in Google Drive without redownloading.+ */+ public async copyFile(+ fileId: string,+ newName?: string,+ parentFolderId?: string+ ): Promise<DriveFileResource> {+ const url = `${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}/copy?fields=id,name,mimeType,size,parents,createdTime,modifiedTime`;+ const body: Record<string, unknown> = {};+ if (newName) body.name = newName;+ if (parentFolderId) body.parents = [parentFolderId];++ return this.request<DriveFileResource>(url, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(body)+ });+ }++ /**+ * Updates file metadata / parents server-side in Google Drive (instantaneous server-side move).+ */+ public async moveFile(+ fileId: string,+ newParentId: string,+ oldParentId?: string,+ newName?: string+ ): Promise<DriveFileResource> {+ const url = new URL(`${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}`);+ url.searchParams.set("addParents", newParentId);+ if (oldParentId) {+ url.searchParams.set("removeParents", oldParentId);+ }+ url.searchParams.set("fields", "id,name,parents,modifiedTime");++ const body: Record<string, unknown> = {};+ if (newName) body.name = newName;++ return this.request<DriveFileResource>(url.toString(), {+ method: "PATCH",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(body)+ });+ }++ /**+ * Sends a file or folder to Google Drive Trash (soft-delete).+ */+ public async trashFile(fileId: string): Promise<DriveFileResource> {+ const url = `${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}?fields=id,trashed`;+ return this.request<DriveFileResource>(url, {+ method: "PATCH",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ trashed: true })+ });+ }++ /**+ * Permanently deletes a file or folder in Google Drive.+ */+ public async deleteFile(fileId: string): Promise<void> {+ const url = `${DRIVE_API_BASE}/files/${encodeURIComponent(fileId)}`;+ await this.request<void>(url, { method: "DELETE" });+ }++ /**+ * Retrieves account storage quota.+ */+ public async getAboutQuota(): Promise<DriveAboutResource> {+ const url = `${DRIVE_API_BASE}/about?fields=storageQuota,user`;+ return this.request<DriveAboutResource>(url, { method: "GET" });+ }++ /**+ * Helper to format a DriveFileResource into a standard StorageObject.+ */+ public toStorageObject(resource: DriveFileResource, virtualPath: string): StorageObject {+ const isFolder = resource.mimeType === "application/vnd.google-apps.folder";++ return {+ id: `gdrive_${resource.id}`,+ path: virtualPath,+ name: resource.name,+ provider: "google-drive",+ providerId: resource.id,+ type: isFolder ? "folder" : "file",+ size: resource.size ? Number(resource.size) : undefined,+ mimeType: resource.mimeType,+ checksum: resource.md5Checksum,+ createdAt: resource.createdTime ? new Date(resource.createdTime) : undefined,+ updatedAt: resource.modifiedTime ? new Date(resource.modifiedTime) : undefined,+ metadata: resource.appProperties+ };+ }+}diff --git a/packages/google-drive/src/api/multipart.ts b/packages/google-drive/src/api/multipart.tsnew file mode 100644index 0000000..7f347a7--- /dev/null+++ b/packages/google-drive/src/api/multipart.ts@@ -0,0 +1,98 @@+import type { StorageInput } from "@byoc/core";+import { Readable } from "node:stream";++/**+ * Converts any supported StorageInput into a Uint8Array.+ */+export async function storageInputToUint8Array(input: StorageInput): Promise<Uint8Array> {+ if (typeof input === "string") {+ return new TextEncoder().encode(input);+ }+ if (input instanceof Uint8Array) {+ return input;+ }+ if (input instanceof ArrayBuffer) {+ return new Uint8Array(input);+ }+ if (typeof Buffer !== "undefined" && Buffer.isBuffer(input)) {+ return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);+ }+ if (typeof Blob !== "undefined" && input instanceof Blob) {+ const arrayBuffer = await input.arrayBuffer();+ return new Uint8Array(arrayBuffer);+ }+ if (input instanceof Readable || (typeof ReadableStream !== "undefined" && input instanceof ReadableStream)) {+ const chunks: Uint8Array[] = [];+ if (input instanceof Readable) {+ for await (const chunk of input) {+ if (typeof chunk === "string") {+ chunks.push(new TextEncoder().encode(chunk));+ } else if (chunk instanceof Uint8Array) {+ chunks.push(chunk);+ } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(chunk)) {+ chunks.push(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));+ }+ }+ } else {+ const reader = (input as ReadableStream).getReader();+ while (true) {+ const { done, value } = await reader.read();+ if (done) break;+ if (value) chunks.push(value);+ }+ }++ const totalLength = chunks.reduce((acc, c) => acc + c.byteLength, 0);+ const result = new Uint8Array(totalLength);+ let offset = 0;+ for (const chunk of chunks) {+ result.set(chunk, offset);+ offset += chunk.byteLength;+ }+ return result;+ }++ throw new Error("Unsupported storage input type.");+}++export interface MultipartUploadPayload {+ body: Uint8Array;+ contentType: string;+}++/**+ * Builds a multipart/related body containing JSON metadata and binary data.+ */+export async function buildMultipartBody(+ metadata: Record<string, unknown>,+ data: StorageInput,+ mimeType: string = "application/octet-stream"+): Promise<MultipartUploadPayload> {+ const boundary = `-------BYOC_BOUNDARY_${Date.now()}_${Math.random().toString(36).substring(2)}`;+ const delimiter = `\r\n--${boundary}\r\n`;+ const closeDelimiter = `\r\n--${boundary}--`;++ const metadataJson = JSON.stringify(metadata);+ const metadataHeader =+ delimiter ++ "Content-Type: application/json; charset=UTF-8\r\n\r\n" ++ metadataJson ++ delimiter ++ `Content-Type: ${mimeType}\r\n\r\n`;++ const headerBytes = new TextEncoder().encode(metadataHeader);+ const fileBytes = await storageInputToUint8Array(data);+ const footerBytes = new TextEncoder().encode(closeDelimiter);++ const totalLength = headerBytes.byteLength + fileBytes.byteLength + footerBytes.byteLength;+ const combined = new Uint8Array(totalLength);++ combined.set(headerBytes, 0);+ combined.set(fileBytes, headerBytes.byteLength);+ combined.set(footerBytes, headerBytes.byteLength + fileBytes.byteLength);++ return {+ body: combined,+ contentType: `multipart/related; boundary=${boundary}`+ };+}diff --git a/packages/google-drive/src/api/resumable.ts b/packages/google-drive/src/api/resumable.tsnew file mode 100644index 0000000..d82165c--- /dev/null+++ b/packages/google-drive/src/api/resumable.ts@@ -0,0 +1,201 @@+import { withRetry, type StorageInput, type UploadProgress } from "@byoc/core";+import { GoogleOAuthClient } from "../auth/oauth-client.js";+import { mapGoogleDriveError } from "../errors/mapper.js";+import { storageInputToUint8Array } from "./multipart.js";+import type { DriveFileResource } from "./types.js";++const DRIVE_UPLOAD_BASE = "https://www.googleapis.com/upload/drive/v3";+export const GOOGLE_DRIVE_CHUNK_ALIGNMENT = 256 * 1024; // 256 KiB+export const DEFAULT_CHUNK_SIZE = 1024 * 1024; // 1 MiB (4 * 256 KiB)++export interface ResumableUploadOptions {+ mimeType?: string;+ chunkSize?: number;+ onProgress?: (progress: UploadProgress) => void;+}++/**+ * ResumableUploader — Implements Google Drive's chunked resumable upload protocol+ * with progress events and network disconnection resumption.+ */+export class ResumableUploader {+ constructor(private readonly oauth: GoogleOAuthClient) {}++ /**+ * Uploads large binary data in chunks using the Google Drive Resumable Upload protocol.+ */+ public async upload(+ metadata: { name: string; parents?: string[]; mimeType?: string; appProperties?: Record<string, string> },+ data: StorageInput,+ options: ResumableUploadOptions = {}+ ): Promise<DriveFileResource> {+ const bytes = await storageInputToUint8Array(data);+ const totalBytes = bytes.byteLength;+ const mimeType = options.mimeType || metadata.mimeType || "application/octet-stream";++ // Align chunk size to 256 KiB boundary+ const rawChunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;+ const chunkSize = Math.max(+ GOOGLE_DRIVE_CHUNK_ALIGNMENT,+ Math.floor(rawChunkSize / GOOGLE_DRIVE_CHUNK_ALIGNMENT) * GOOGLE_DRIVE_CHUNK_ALIGNMENT+ );++ // 1. Initiate Resumable Upload Session+ const sessionUri = await this.initiateSession(metadata, totalBytes, mimeType);++ // 2. Transmit Chunks+ return this.transmitChunks(sessionUri, bytes, totalBytes, chunkSize, mimeType, options.onProgress);+ }++ /**+ * Initiates a resumable upload session and extracts the Location session URI.+ */+ private async initiateSession(+ metadata: Record<string, unknown>,+ totalBytes: number,+ mimeType: string+ ): Promise<string> {+ const url = `${DRIVE_UPLOAD_BASE}/files?uploadType=resumable&fields=id,name,mimeType,size,parents,createdTime,modifiedTime,md5Checksum,appProperties`;++ return withRetry(async () => {+ const accessToken = await this.oauth.getAccessToken();++ const headers = new Headers({+ Authorization: `Bearer ${accessToken}`,+ "Content-Type": "application/json; charset=UTF-8",+ "X-Upload-Content-Type": mimeType,+ "X-Upload-Content-Length": String(totalBytes)+ });++ const response = await fetch(url, {+ method: "POST",+ headers,+ body: JSON.stringify(metadata)+ });++ if (!response.ok) {+ let errorData: unknown;+ try {+ errorData = await response.json();+ } catch {+ errorData = await response.text();+ }+ throw mapGoogleDriveError({ status: response.status, data: errorData });+ }++ const sessionUri = response.headers.get("Location");+ if (!sessionUri) {+ throw mapGoogleDriveError({+ status: 500,+ data: { error: { message: "Google Drive did not return a Location header for resumable upload." } }+ });+ }++ return sessionUri;+ });+ }++ /**+ * Transmits data chunks to the session URI until complete.+ */+ private async transmitChunks(+ sessionUri: string,+ bytes: Uint8Array,+ totalBytes: number,+ chunkSize: number,+ mimeType: string,+ onProgress?: (progress: UploadProgress) => void+ ): Promise<DriveFileResource> {+ let offset = 0;++ // Handle empty 0-byte file edge case+ if (totalBytes === 0) {+ const response = await fetch(sessionUri, {+ method: "PUT",+ headers: {+ "Content-Length": "0",+ "Content-Range": "bytes */0"+ }+ });+ return (await response.json()) as DriveFileResource;+ }++ while (offset < totalBytes) {+ const chunkEnd = Math.min(offset + chunkSize, totalBytes);+ const chunk = bytes.subarray(offset, chunkEnd);+ const contentRange = `bytes ${offset}-${chunkEnd - 1}/${totalBytes}`;++ let chunkUploaded = false;+ let finalResource: DriveFileResource | undefined;++ await withRetry(async () => {+ const response = await fetch(sessionUri, {+ method: "PUT",+ headers: {+ "Content-Type": mimeType,+ "Content-Range": contentRange+ },+ body: chunk as unknown as BodyInit+ });++ // 308 Resume Incomplete indicates chunk was saved successfully+ if (response.status === 308) {+ const rangeHeader = response.headers.get("Range");+ if (rangeHeader) {+ const match = rangeHeader.match(/bytes=0-(\d+)/);+ if (match && match[1]) {+ offset = Number(match[1]) + 1;+ } else {+ offset = chunkEnd;+ }+ } else {+ offset = chunkEnd;+ }+ chunkUploaded = true;+ return;+ }++ // 200 or 201 indicates entire file has been assembled and uploaded+ if (response.status === 200 || response.status === 201) {+ finalResource = (await response.json()) as DriveFileResource;+ offset = totalBytes;+ chunkUploaded = true;+ return;+ }++ // If error response, throw mapped error to trigger retry or failure+ let errorData: unknown;+ try {+ errorData = await response.json();+ } catch {+ errorData = await response.text();+ }+ throw mapGoogleDriveError({ status: response.status, data: errorData });+ }, {+ maxRetries: 3,+ baseDelayMs: 1000,+ shouldRetry: (_err) => true // Auto-recover on network interruption+ });++ if (chunkUploaded) {+ if (onProgress) {+ const percentage = Math.min(100, Math.round((offset / totalBytes) * 100));+ onProgress({+ bytesUploaded: offset,+ totalBytes,+ percentage+ });+ }+ }++ if (finalResource) {+ return finalResource;+ }+ }++ throw mapGoogleDriveError({+ status: 500,+ data: { error: { message: "Resumable upload loop terminated without receiving final completion resource." } }+ });+ }+}diff --git a/packages/google-drive/src/api/types.ts b/packages/google-drive/src/api/types.tsnew file mode 100644index 0000000..989c4db--- /dev/null+++ b/packages/google-drive/src/api/types.ts@@ -0,0 +1,42 @@+/**+ * Schema for Google Drive v3 File Resource.+ */+export interface DriveFileResource {+ id: string;+ name: string;+ mimeType: string;+ parents?: string[];+ size?: string; // Google Drive returns file size as string in bytes+ createdTime?: string;+ modifiedTime?: string;+ md5Checksum?: string;+ trashed?: boolean;+ properties?: Record<string, string>;+ appProperties?: Record<string, string>;+}++/**+ * Schema for Google Drive v3 File List Response.+ */+export interface DriveFileListResponse {+ kind: string;+ nextPageToken?: string;+ incompleteSearch?: boolean;+ files: DriveFileResource[];+}++/**+ * Schema for Google Drive v3 About Resource.+ */+export interface DriveAboutResource {+ storageQuota?: {+ limit?: string; // Total limit in bytes+ usage?: string; // Used in bytes+ usageInDrive?: string;+ usageInDriveTrash?: string;+ };+ user?: {+ displayName?: string;+ emailAddress?: string;+ };+}diff --git a/packages/google-drive/src/auth/oauth-client.ts b/packages/google-drive/src/auth/oauth-client.tsnew file mode 100644index 0000000..fb54118--- /dev/null+++ b/packages/google-drive/src/auth/oauth-client.ts@@ -0,0 +1,276 @@+import { BYOCErrorCode, StorageError } from "@byoc/core";+import {+ GoogleDriveScope,+ type AuthorizationUrlOptions,+ type ExchangeCodeOptions,+ type GoogleDriveAuthConfig,+ type GoogleDriveTokenSession,+ type GoogleTokenStorage+} from "./types.js";+import { InMemoryTokenStorage } from "./storage.js";+import { mapGoogleDriveError } from "../errors/mapper.js";++const GOOGLE_AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";+const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";+const GOOGLE_REVOKE_ENDPOINT = "https://oauth2.googleapis.com/revoke";++/**+ * GoogleOAuthClient — Manages OAuth 2.0 PKCE handshake, token refresh, and storage.+ */+export class GoogleOAuthClient {+ public readonly config: GoogleDriveAuthConfig;+ public readonly storage: GoogleTokenStorage;++ constructor(config: GoogleDriveAuthConfig) {+ if (!config || !config.clientId) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "GoogleOAuthClient requires a valid 'clientId'.",+ provider: "google-drive",+ retryable: false+ });+ }++ this.config = {+ ...config,+ scopes: config.scopes && config.scopes.length > 0 ? config.scopes : [GoogleDriveScope.FILE]+ };++ this.storage = config.tokenStorage ?? new InMemoryTokenStorage(config.session);+ }++ /**+ * Generates the Google OAuth 2.0 consent URL.+ */+ public getAuthorizationUrl(options: AuthorizationUrlOptions = {}): string {+ const scopes = options.scopes ?? this.config.scopes ?? [GoogleDriveScope.FILE];+ const redirectUri = options.redirectUri ?? this.config.redirectUri;++ if (!redirectUri) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Cannot generate authorization URL: 'redirectUri' is required.",+ provider: "google-drive",+ retryable: false+ });+ }++ const url = new URL(GOOGLE_AUTH_ENDPOINT);+ url.searchParams.set("client_id", this.config.clientId);+ url.searchParams.set("redirect_uri", redirectUri);+ url.searchParams.set("response_type", "code");+ url.searchParams.set("scope", scopes.join(" "));+ url.searchParams.set("access_type", options.accessType ?? "offline");+ url.searchParams.set("prompt", options.prompt ?? "consent");++ if (options.state) {+ url.searchParams.set("state", options.state);+ }++ if (options.codeChallenge) {+ url.searchParams.set("code_challenge", options.codeChallenge);+ url.searchParams.set("code_challenge_method", options.codeChallengeMethod ?? "S256");+ }++ return url.toString();+ }++ /**+ * Exchanges an authorization code for access and refresh tokens.+ */+ public async exchangeCode(options: ExchangeCodeOptions): Promise<GoogleDriveTokenSession> {+ const redirectUri = options.redirectUri ?? this.config.redirectUri;++ if (!redirectUri) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Cannot exchange authorization code: 'redirectUri' is required.",+ provider: "google-drive",+ retryable: false+ });+ }++ const bodyParams = new URLSearchParams();+ bodyParams.set("client_id", this.config.clientId);+ if (this.config.clientSecret) {+ bodyParams.set("client_secret", this.config.clientSecret);+ }+ bodyParams.set("code", options.code);+ bodyParams.set("grant_type", "authorization_code");+ bodyParams.set("redirect_uri", redirectUri);++ if (options.codeVerifier) {+ bodyParams.set("code_verifier", options.codeVerifier);+ }++ try {+ const response = await fetch(GOOGLE_TOKEN_ENDPOINT, {+ method: "POST",+ headers: {+ "Content-Type": "application/x-www-form-urlencoded"+ },+ body: bodyParams.toString()+ });++ const data = (await response.json()) as any;++ if (!response.ok || data.error) {+ throw mapGoogleDriveError({+ status: response.status,+ data: { error: { message: data.error_description || data.error, code: response.status } }+ });+ }++ const session: GoogleDriveTokenSession = {+ accessToken: data.access_token,+ refreshToken: data.refresh_token,+ tokenType: data.token_type,+ scope: data.scope,+ expiresAt: data.expires_in ? Date.now() + Number(data.expires_in) * 1000 : undefined+ };++ await this.storage.set(session);+ return session;+ } catch (err) {+ throw mapGoogleDriveError(err);+ }+ }++ /**+ * Retrieves a valid access token, automatically refreshing if expired.+ */+ public async getAccessToken(): Promise<string> {+ const session = await this.storage.get();++ if (!session || !session.accessToken) {+ throw new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "No active Google Drive session found. Please authenticate via connect().",+ provider: "google-drive",+ statusCode: 401,+ retryable: false+ });+ }++ // Check if token is expired with a 60-second safety margin+ const safetyMarginMs = 60 * 1000;+ const isExpired = session.expiresAt ? Date.now() + safetyMarginMs >= session.expiresAt : false;++ if (isExpired) {+ if (session.refreshToken) {+ const refreshed = await this.refreshAccessToken(session.refreshToken);+ return refreshed.accessToken;+ } else {+ throw new StorageError({+ code: BYOCErrorCode.TOKEN_EXPIRED,+ message: "Google Drive access token has expired and no refresh token is available. Re-authentication required.",+ provider: "google-drive",+ statusCode: 401,+ retryable: false+ });+ }+ }++ return session.accessToken;+ }++ /**+ * Refreshes an expired access token using the refresh token.+ */+ public async refreshAccessToken(refreshTokenOverride?: string): Promise<GoogleDriveTokenSession> {+ const currentSession = await this.storage.get();+ const refreshToken = refreshTokenOverride ?? currentSession?.refreshToken;++ if (!refreshToken) {+ throw new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Cannot refresh token: No refresh token available in active session.",+ provider: "google-drive",+ statusCode: 401,+ retryable: false+ });+ }++ const bodyParams = new URLSearchParams();+ bodyParams.set("client_id", this.config.clientId);+ if (this.config.clientSecret) {+ bodyParams.set("client_secret", this.config.clientSecret);+ }+ bodyParams.set("refresh_token", refreshToken);+ bodyParams.set("grant_type", "refresh_token");++ try {+ const response = await fetch(GOOGLE_TOKEN_ENDPOINT, {+ method: "POST",+ headers: {+ "Content-Type": "application/x-www-form-urlencoded"+ },+ body: bodyParams.toString()+ });++ const data = (await response.json()) as any;++ if (!response.ok || data.error) {+ throw mapGoogleDriveError({+ status: response.status,+ data: { error: { message: data.error_description || data.error, code: response.status } }+ });+ }++ const updatedSession: GoogleDriveTokenSession = {+ accessToken: data.access_token,+ refreshToken: data.refresh_token ?? refreshToken, // Retain existing refresh token if not rotated+ tokenType: data.token_type ?? currentSession?.tokenType,+ scope: data.scope ?? currentSession?.scope,+ expiresAt: data.expires_in ? Date.now() + Number(data.expires_in) * 1000 : undefined+ };++ await this.storage.set(updatedSession);+ return updatedSession;+ } catch (err) {+ throw mapGoogleDriveError(err);+ }+ }++ /**+ * Revokes the active access or refresh token with Google and clears stored session.+ */+ public async revoke(): Promise<void> {+ const session = await this.storage.get();+ const tokenToRevoke = session?.refreshToken ?? session?.accessToken;++ if (tokenToRevoke) {+ try {+ await fetch(`${GOOGLE_REVOKE_ENDPOINT}?token=${encodeURIComponent(tokenToRevoke)}`, {+ method: "POST",+ headers: {+ "Content-Type": "application/x-www-form-urlencoded"+ }+ });+ } catch {+ // Revocation network errors should not prevent local session cleanup+ }+ }++ await this.storage.clear();+ }++ /**+ * Sets an existing active session manually.+ */+ public async setSession(session: GoogleDriveTokenSession): Promise<void> {+ await this.storage.set(session);+ }++ /**+ * Checks if an active session exists.+ */+ public async hasValidSession(): Promise<boolean> {+ const session = await this.storage.get();+ if (!session || !session.accessToken) return false;+ if (session.expiresAt && Date.now() >= session.expiresAt) {+ return !!session.refreshToken;+ }+ return true;+ }+}diff --git a/packages/google-drive/src/auth/pkce.ts b/packages/google-drive/src/auth/pkce.tsnew file mode 100644index 0000000..3e5c604--- /dev/null+++ b/packages/google-drive/src/auth/pkce.ts@@ -0,0 +1,47 @@+import { webcrypto } from "node:crypto";++const cryptoObj = (typeof crypto !== "undefined" ? crypto : webcrypto) as Crypto;++/**+ * Converts an ArrayBuffer to a base64url-encoded string (RFC 7636).+ */+function base64UrlEncode(buffer: ArrayBuffer): string {+ const bytes = new Uint8Array(buffer);+ let binary = "";+ for (let i = 0; i < bytes.byteLength; i++) {+ binary += String.fromCharCode(bytes[i]!);+ }+ return btoa(binary)+ .replace(/\+/g, "-")+ .replace(/\//g, "_")+ .replace(/=+$/, "");+}++/**+ * Generates a cryptographically random code_verifier string (43 to 128 characters).+ */+export function generateCodeVerifier(length: number = 64): string {+ const validLength = Math.max(43, Math.min(128, length));+ const randomBytes = new Uint8Array(validLength);+ cryptoObj.getRandomValues(randomBytes);+ return base64UrlEncode(randomBytes.buffer).substring(0, validLength);+}++/**+ * Generates an S256 code_challenge from a code_verifier (RFC 7636).+ */+export async function generateCodeChallenge(verifier: string): Promise<string> {+ const encoder = new TextEncoder();+ const data = encoder.encode(verifier);+ const digest = await cryptoObj.subtle.digest("SHA-256", data);+ return base64UrlEncode(digest);+}++/**+ * Generates a cryptographically secure random state string to protect against CSRF.+ */+export function generateOAuthState(length: number = 32): string {+ const randomBytes = new Uint8Array(length);+ cryptoObj.getRandomValues(randomBytes);+ return base64UrlEncode(randomBytes.buffer).substring(0, length);+}diff --git a/packages/google-drive/src/auth/storage.ts b/packages/google-drive/src/auth/storage.tsnew file mode 100644index 0000000..aeaa53b--- /dev/null+++ b/packages/google-drive/src/auth/storage.ts@@ -0,0 +1,100 @@+import type { GoogleDriveTokenSession, GoogleTokenStorage } from "./types.js";+import crypto from "node:crypto";+import fs from "node:fs";++/**+ * Default in-memory token storage.+ * Sessions are preserved during application runtime and cleared on disconnect/restart.+ */+export class InMemoryTokenStorage implements GoogleTokenStorage {+ private session: GoogleDriveTokenSession | null = null;++ constructor(initialSession?: GoogleDriveTokenSession) {+ if (initialSession) {+ this.session = { ...initialSession };+ }+ }++ public get(): GoogleDriveTokenSession | null {+ return this.session ? { ...this.session } : null;+ }++ public set(session: GoogleDriveTokenSession): void {+ this.session = { ...session };+ }++ public clear(): void {+ this.session = null;+ }+}++export interface EncryptedFileStorageOptions {+ filePath: string;+ encryptionKey: string | Buffer;+}++/**+ * Encrypted file-based token storage using AES-256-GCM authenticated encryption.+ * Persists OAuth refresh tokens securely across application restarts.+ */+export class EncryptedFileTokenStorage implements GoogleTokenStorage {+ private readonly filePath: string;+ private readonly key: Buffer;++ constructor(options: EncryptedFileStorageOptions) {+ this.filePath = options.filePath;+ if (typeof options.encryptionKey === "string") {+ this.key = crypto.createHash("sha256").update(options.encryptionKey).digest();+ } else {+ this.key = options.encryptionKey;+ }+ }++ public get(): GoogleDriveTokenSession | null {+ if (!fs.existsSync(this.filePath)) {+ return null;+ }++ try {+ const raw = fs.readFileSync(this.filePath, "utf8");+ const { iv, tag, data } = JSON.parse(raw);++ const decipher = crypto.createDecipheriv("aes-256-gcm", this.key, Buffer.from(iv, "hex"));+ decipher.setAuthTag(Buffer.from(tag, "hex"));++ let decrypted = decipher.update(data, "hex", "utf8");+ decrypted += decipher.final("utf8");++ return JSON.parse(decrypted) as GoogleDriveTokenSession;+ } catch {+ return null;+ }+ }++ public set(session: GoogleDriveTokenSession): void {+ const iv = crypto.randomBytes(12);+ const cipher = crypto.createCipheriv("aes-256-gcm", this.key, iv);++ let encrypted = cipher.update(JSON.stringify(session), "utf8", "hex");+ encrypted += cipher.final("hex");+ const tag = cipher.getAuthTag();++ const payload = JSON.stringify({+ iv: iv.toString("hex"),+ tag: tag.toString("hex"),+ data: encrypted+ });++ fs.writeFileSync(this.filePath, payload, "utf8");+ }++ public clear(): void {+ if (fs.existsSync(this.filePath)) {+ try {+ fs.unlinkSync(this.filePath);+ } catch {+ // Ignore deletion errors+ }+ }+ }+}diff --git a/packages/google-drive/src/auth/types.ts b/packages/google-drive/src/auth/types.tsnew file mode 100644index 0000000..20acd38--- /dev/null+++ b/packages/google-drive/src/auth/types.ts@@ -0,0 +1,60 @@+/**+ * Permitted Google Drive OAuth scopes.+ * BYOC defaults strictly to `drive.file` to avoid Google Restricted Scope verification barriers.+ */+export const GoogleDriveScope = {+ /** Access only to files created or opened by this app (Standard Default) */+ FILE: "https://www.googleapis.com/auth/drive.file",+ /** Access to application data folder for hidden sync/indexes */+ APP_DATA: "https://www.googleapis.com/auth/drive.appdata",+ /** Read-only access to files created or opened by this app */+ FILE_READONLY: "https://www.googleapis.com/auth/drive.file.readonly"+} as const;++export type GoogleDriveScope = typeof GoogleDriveScope[keyof typeof GoogleDriveScope];++export interface GoogleDriveTokenSession {+ accessToken: string;+ refreshToken?: string;+ expiresAt?: number; // Unix timestamp in ms+ tokenType?: string;+ scope?: string;+}++export interface GoogleTokenStorage {+ get(): Promise<GoogleDriveTokenSession | null> | GoogleDriveTokenSession | null;+ set(session: GoogleDriveTokenSession): Promise<void> | void;+ clear(): Promise<void> | void;+}++export interface AuthorizationUrlOptions {+ state?: string;+ codeChallenge?: string;+ codeChallengeMethod?: "S256" | "plain";+ redirectUri?: string;+ prompt?: "consent" | "select_account" | "none";+ accessType?: "offline" | "online";+ scopes?: GoogleDriveScope[];+}++export interface ExchangeCodeOptions {+ code: string;+ codeVerifier?: string;+ redirectUri?: string;+}++export interface GoogleDriveAuthConfig {+ clientId: string;+ clientSecret?: string;+ redirectUri?: string;+ scopes?: GoogleDriveScope[];+ tokenStorage?: GoogleTokenStorage;+ /** Existing active session (optional, for pre-authenticated clients) */+ session?: GoogleDriveTokenSession;+}++export interface GoogleDriveProviderConfig {+ auth: GoogleDriveAuthConfig;+ /** App root folder name in Drive (defaults to "BYOC") */+ rootFolderName?: string;+}diff --git a/packages/google-drive/src/errors/mapper.ts b/packages/google-drive/src/errors/mapper.tsnew file mode 100644index 0000000..5ee8356--- /dev/null+++ b/packages/google-drive/src/errors/mapper.ts@@ -0,0 +1,122 @@+import { BYOCErrorCode, StorageError } from "@byoc/core";++export interface GoogleApiErrorResponse {+ error?: {+ code?: number;+ message?: string;+ errors?: Array<{+ message?: string;+ domain?: string;+ reason?: string;+ location?: string;+ }>;+ status?: string;+ };+}++/**+ * Maps raw Google Drive REST API error responses and HTTP status codes+ * to standard normalized BYOC StorageError instances.+ */+export function mapGoogleDriveError(rawError: unknown): StorageError {+ if (StorageError.isStorageError(rawError)) {+ return rawError;+ }++ const err = rawError as any;+ const status = Number(err?.status ?? err?.code ?? err?.statusCode ?? err?.response?.status ?? 0);+ const responseData: GoogleApiErrorResponse | undefined = err?.response?.data ?? err?.data;+ const reason = responseData?.error?.errors?.[0]?.reason ?? err?.reason ?? "";+ const rawMessage = responseData?.error?.message ?? err?.message ?? "An unknown Google Drive error occurred.";++ // 1. Authentication / Token issues+ if (status === 401 || reason === "authError" || reason === "invalid_grant") {+ return new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: `Google Drive authentication required: ${rawMessage}`,+ provider: "google-drive",+ statusCode: 401,+ retryable: false,+ rawError+ });+ }++ // 2. Storage Quota Exceeded+ if (+ reason === "storageQuotaExceeded" ||+ reason === "quotaExceeded" ||+ rawMessage.toLowerCase().includes("quota exceeded")+ ) {+ return new StorageError({+ code: BYOCErrorCode.QUOTA_EXCEEDED,+ message: `Google Drive storage quota exceeded: ${rawMessage}`,+ provider: "google-drive",+ statusCode: 403,+ retryable: false,+ rawError+ });+ }++ // 3. Rate limiting / Throttling+ if (+ status === 429 ||+ reason === "userRateLimitExceeded" ||+ reason === "rateLimitExceeded" ||+ reason === "dailyLimitExceeded"+ ) {+ return new StorageError({+ code: BYOCErrorCode.RATE_LIMITED,+ message: `Google Drive rate limit exceeded: ${rawMessage}`,+ provider: "google-drive",+ statusCode: 429,+ retryable: true,+ rawError+ });+ }++ // 4. File or folder not found+ if (status === 404 || reason === "notFound") {+ return new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: `Google Drive object not found: ${rawMessage}`,+ provider: "google-drive",+ statusCode: 404,+ retryable: false,+ rawError+ });+ }++ // 5. Permission denied+ if (status === 403 || reason === "forbidden" || reason === "insufficientFilePermissions") {+ return new StorageError({+ code: BYOCErrorCode.PERMISSION_DENIED,+ message: `Google Drive permission denied: ${rawMessage}`,+ provider: "google-drive",+ statusCode: 403,+ retryable: false,+ rawError+ });+ }++ // 6. Provider Unavailable / Transient Backend Error+ if (status === 500 || status === 502 || status === 503 || status === 504 || reason === "backendError") {+ return new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: `Google Drive service temporarily unavailable (${status || "5xx"}): ${rawMessage}`,+ provider: "google-drive",+ statusCode: status || 503,+ retryable: true,+ rawError+ });+ }++ // Fallback generic error+ return new StorageError({+ code: BYOCErrorCode.UPLOAD_FAILED,+ message: `Google Drive error: ${rawMessage}`,+ provider: "google-drive",+ statusCode: status || undefined,+ retryable: false,+ rawError+ });+}diff --git a/packages/google-drive/src/index.ts b/packages/google-drive/src/index.tsnew file mode 100644index 0000000..22ea0da--- /dev/null+++ b/packages/google-drive/src/index.ts@@ -0,0 +1,40 @@+export { GoogleDriveProvider } from "./adapter.js";+export { GoogleOAuthClient } from "./auth/oauth-client.js";+export {+ InMemoryTokenStorage,+ EncryptedFileTokenStorage,+ type EncryptedFileStorageOptions+} from "./auth/storage.js";+export {+ generateCodeVerifier,+ generateCodeChallenge,+ generateOAuthState+} from "./auth/pkce.js";+export {+ GoogleDriveScope,+ type GoogleDriveAuthConfig,+ type GoogleDriveProviderConfig,+ type GoogleDriveTokenSession,+ type GoogleTokenStorage,+ type AuthorizationUrlOptions,+ type ExchangeCodeOptions+} from "./auth/types.js";+export { DriveHttpClient } from "./api/http.js";+export { buildMultipartBody, storageInputToUint8Array, type MultipartUploadPayload } from "./api/multipart.js";+export {+ ResumableUploader,+ DEFAULT_CHUNK_SIZE,+ GOOGLE_DRIVE_CHUNK_ALIGNMENT,+ type ResumableUploadOptions+} from "./api/resumable.js";+export type { DriveFileResource, DriveFileListResponse, DriveAboutResource } from "./api/types.js";+export { mapGoogleDriveError, type GoogleApiErrorResponse } from "./errors/mapper.js";+export {+ GoogleDrivePathResolver,+ LruTtlPathCache,+ InMemoryPathCache,+ escapeDriveQueryValue,+ type PathCache,+ type CacheOptions,+ type GoogleDriveResolvedNode+} from "./paths/virtual-path.js";diff --git a/packages/google-drive/src/paths/virtual-path.ts b/packages/google-drive/src/paths/virtual-path.tsnew file mode 100644index 0000000..2cf091f--- /dev/null+++ b/packages/google-drive/src/paths/virtual-path.ts@@ -0,0 +1,281 @@+import { BYOCErrorCode, StorageError, getBasename, getDirname, normalizeVirtualPath } from "@byoc/core";+import type { DriveHttpClient } from "../api/http.js";++/**+ * Resolved object reference within Google Drive.+ */+export interface GoogleDriveResolvedNode {+ readonly id: string;+ readonly name: string;+ readonly parentId?: string;+ readonly isFolder: boolean;+ readonly mimeType?: string;+ readonly size?: number;+}++/**+ * Interface for caching virtual path -> Google Drive file/folder ID mappings.+ */+export interface PathCache {+ get(path: string): Promise<string | undefined> | string | undefined;+ set(path: string, id: string): Promise<void> | void;+ delete(path: string): Promise<void> | void;+ clear(): Promise<void> | void;+}++export interface CacheOptions {+ /** Time-to-live in milliseconds for cached path entries (default: 5 minutes) */+ ttlMs?: number;+ /** Maximum number of paths retained in memory (default: 1000) */+ maxSize?: number;+}++interface CacheEntry {+ id: string;+ expiresAt: number;+}++/**+ * High-performance LRU + TTL Path Cache for Google Drive virtual paths.+ */+export class LruTtlPathCache implements PathCache {+ private readonly cache = new Map<string, CacheEntry>();+ private readonly ttlMs: number;+ private readonly maxSize: number;++ constructor(options: CacheOptions = {}) {+ this.ttlMs = options.ttlMs ?? 5 * 60 * 1000; // 5 minutes default+ this.maxSize = options.maxSize ?? 1000;+ }++ public get(path: string): string | undefined {+ const entry = this.cache.get(path);+ if (!entry) return undefined;++ // Check expiration+ if (Date.now() > entry.expiresAt) {+ this.cache.delete(path);+ return undefined;+ }++ // Refresh LRU order+ this.cache.delete(path);+ this.cache.set(path, entry);++ return entry.id;+ }++ public set(path: string, id: string): void {+ if (this.cache.has(path)) {+ this.cache.delete(path);+ } else if (this.cache.size >= this.maxSize) {+ // Evict oldest entry (first item in Map)+ const firstKey = this.cache.keys().next().value;+ if (firstKey) {+ this.cache.delete(firstKey);+ }+ }++ this.cache.set(path, {+ id,+ expiresAt: Date.now() + this.ttlMs+ });+ }++ public delete(path: string): void {+ this.cache.delete(path);+ }++ public clear(): void {+ this.cache.clear();+ }+}++/**+ * Backward-compatible InMemoryPathCache alias.+ */+export class InMemoryPathCache extends LruTtlPathCache {}++/**+ * Escapes characters for Google Drive query string parameters.+ * According to Drive API v3 documentation, single quotes and backslashes must be escaped with a backslash.+ */+export function escapeDriveQueryValue(value: string): string {+ return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");+}++/**+ * GoogleDrivePathResolver — Maps virtual POSIX paths to Google Drive folder/file node IDs,+ * automatically creating nested hierarchies and recovering from out-of-band Drive modifications.+ */+export class GoogleDrivePathResolver {+ private rootFolderId?: string;++ constructor(+ private readonly http: DriveHttpClient,+ private readonly rootFolderName: string = "BYOC",+ private readonly cache: PathCache = new LruTtlPathCache()+ ) {}++ /**+ * Resolves or creates the root application folder in Google Drive.+ */+ public async ensureRootFolder(forceRefresh: boolean = false): Promise<string> {+ if (this.rootFolderId && !forceRefresh) {+ return this.rootFolderId;+ }++ const cachedRoot = await this.cache.get("__ROOT__");+ if (cachedRoot && !forceRefresh) {+ this.rootFolderId = cachedRoot;+ return cachedRoot;+ }++ const folderName = this.rootFolderName || "BYOC";+ const escapedName = escapeDriveQueryValue(folderName);+ const query = `name = '${escapedName}' and 'root' in parents and mimeType = 'application/vnd.google-apps.folder' and trashed = false`;+ const listRes = await this.http.listFiles(query, 1);++ if (listRes.files && listRes.files.length > 0 && listRes.files[0]) {+ this.rootFolderId = listRes.files[0].id;+ await this.cache.set("__ROOT__", this.rootFolderId);+ return this.rootFolderId;+ }++ // Create root folder under Drive root+ const created = await this.http.createFolder(folderName, "root");+ this.rootFolderId = created.id;+ await this.cache.set("__ROOT__", this.rootFolderId);+ return this.rootFolderId;+ }++ /**+ * Resolves the parent folder ID for a virtual path, creating any missing intermediate folders.+ */+ public async resolveParentFolderId(virtualPath: string): Promise<string> {+ const normalized = normalizeVirtualPath(virtualPath);+ const dirname = getDirname(normalized);++ if (!dirname) {+ return this.ensureRootFolder();+ }++ return this.resolveOrCreateFolderPath(dirname);+ }++ /**+ * Recursively resolves or creates a folder path structure (e.g. "users/123/documents").+ */+ public async resolveOrCreateFolderPath(folderPath: string): Promise<string> {+ const normalized = normalizeVirtualPath(folderPath);+ if (!normalized) {+ return this.ensureRootFolder();+ }++ const cached = await this.cache.get(normalized);+ if (cached) return cached;++ const segments = normalized.split("/");+ let currentParentId = await this.ensureRootFolder();+ let currentPath = "";++ for (const segment of segments) {+ currentPath = currentPath ? `${currentPath}/${segment}` : segment;+ const segmentCached = await this.cache.get(currentPath);++ if (segmentCached) {+ currentParentId = segmentCached;+ continue;+ }++ // Search for folder under current parent with query escaping+ const escapedSegment = escapeDriveQueryValue(segment);+ const query = `name = '${escapedSegment}' and '${currentParentId}' in parents and mimeType = 'application/vnd.google-apps.folder' and trashed = false`;+ const listRes = await this.http.listFiles(query, 5);++ if (listRes.files && listRes.files.length > 0 && listRes.files[0]) {+ // Pick newest if duplicates exist+ currentParentId = listRes.files[0].id;+ } else {+ const created = await this.http.createFolder(segment, currentParentId);+ currentParentId = created.id;+ }++ await this.cache.set(currentPath, currentParentId);+ }++ return currentParentId;+ }++ /**+ * Resolves a file ID from its virtual path.+ * If `skipCache` is true, queries Google Drive directly.+ */+ public async resolveFileId(+ virtualPath: string,+ options: { skipCache?: boolean } = {}+ ): Promise<string> {+ const normalized = normalizeVirtualPath(virtualPath);+ if (!normalized) {+ return this.ensureRootFolder();+ }++ if (!options.skipCache) {+ const cached = await this.cache.get(normalized);+ if (cached) return cached;+ }++ const filename = getBasename(normalized);+ const parentFolderId = await this.resolveParentFolderId(normalized);++ const escapedFilename = escapeDriveQueryValue(filename);+ const query = `name = '${escapedFilename}' and '${parentFolderId}' in parents and trashed = false`;+ const listRes = await this.http.listFiles(query, 10);++ if (!listRes.files || listRes.files.length === 0 || !listRes.files[0]) {+ await this.cache.delete(normalized);+ throw new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: `Object not found at path: "${normalized}"`,+ provider: "google-drive",+ statusCode: 404,+ retryable: false+ });+ }++ // Sort by modifiedTime descending if duplicate filenames exist+ const sortedFiles = [...listRes.files].sort((a, b) => {+ const timeA = a.modifiedTime ? new Date(a.modifiedTime).getTime() : 0;+ const timeB = b.modifiedTime ? new Date(b.modifiedTime).getTime() : 0;+ return timeB - timeA;+ });++ const fileId = sortedFiles[0]!.id;+ await this.cache.set(normalized, fileId);+ return fileId;+ }++ /**+ * Invalidate cached mapping for a path (used when 404 is encountered).+ */+ public async invalidate(virtualPath: string): Promise<void> {+ const normalized = normalizeVirtualPath(virtualPath);+ await this.cache.delete(normalized);+ }++ /**+ * Set or update cached mapping for a virtual path.+ */+ public async setCached(virtualPath: string, fileId: string): Promise<void> {+ const normalized = normalizeVirtualPath(virtualPath);+ await this.cache.set(normalized, fileId);+ }++ /**+ * Clears entire path cache (e.g. on disconnect or account switch).+ */+ public async clearCache(): Promise<void> {+ this.rootFolderId = undefined;+ await this.cache.clear();+ }+}diff --git a/packages/google-drive/tests/adapter.test.ts b/packages/google-drive/tests/adapter.test.tsnew file mode 100644index 0000000..3732d02--- /dev/null+++ b/packages/google-drive/tests/adapter.test.ts@@ -0,0 +1,210 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { GoogleDriveProvider } from "../src/adapter.js";+import { GoogleDriveScope } from "../src/auth/types.js";+import { StorageError, BYOCErrorCode } from "@byoc/core";++describe("GoogleDriveProvider REST API Operations", () => {+ const originalFetch = global.fetch;++ beforeEach(() => {+ global.fetch = vi.fn();+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ it("instantiates correctly with valid configuration", () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id.apps.googleusercontent.com",+ scopes: [GoogleDriveScope.FILE]+ },+ rootFolderName: "TestApp"+ });++ expect(provider).toBeDefined();+ expect(provider.config.rootFolderName).toBe("TestApp");+ expect(provider.oauth).toBeDefined();+ });++ it("throws StorageError if clientId is missing", () => {+ expect(() => new GoogleDriveProvider({ auth: {} as any })).toThrowError(StorageError);+ });++ it("exposes accurate provider manifest and capabilities", () => {+ const provider = new GoogleDriveProvider({+ auth: { clientId: "test-client-id" }+ });++ const manifest = provider.manifest();+ expect(manifest.id).toBe("google-drive");+ expect(manifest.name).toBe("Google Drive");+ expect(manifest.category).toBe("personal-cloud");++ const caps = provider.capabilities();+ expect(caps.folders).toBe(true);+ expect(caps.quota).toBe(true);+ });++ it("throws AUTH_REQUIRED on connect() if no session exists", async () => {+ const provider = new GoogleDriveProvider({+ auth: { clientId: "test-client-id" }+ });++ await expect(provider.connect()).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.AUTH_REQUIRED+ })+ );+ });++ it("connects and executes real REST upload", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ },+ rootFolderName: "TestApp"+ });++ // 1. Root folder lookup mock+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ files: [{ id: "root-folder-id", name: "TestApp" }] })+ });++ await provider.connect();++ // 2. Upload file mock+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ id: "uploaded-file-id-123",+ name: "report.pdf",+ mimeType: "application/pdf",+ size: "1024",+ createdTime: new Date().toISOString()+ })+ });++ const result = await provider.upload("report.pdf", "PDF Data", { mimeType: "application/pdf" });+ expect(result.id).toBe("gdrive_uploaded-file-id-123");+ expect(result.path).toBe("report.pdf");+ expect(result.provider).toBe("google-drive");+ });++ it("executes list operations inside root folder", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ // Root folder lookup mock+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ files: [{ id: "root-folder-id" }] })+ });++ // List files mock+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ files: [+ { id: "f1", name: "doc.txt", mimeType: "text/plain", size: "50" },+ { id: "f2", name: "Images", mimeType: "application/vnd.google-apps.folder" }+ ]+ })+ });++ const list = await provider.list();+ expect(list.length).toBe(2);+ expect(list[0]?.name).toBe("doc.txt");+ expect(list[0]?.type).toBe("file");+ expect(list[1]?.name).toBe("Images");+ expect(list[1]?.type).toBe("folder");+ });++ it("fetches quota from about endpoint", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ storageQuota: {+ limit: "107374182400", // 100 GB+ usage: "10737418240" // 10 GB+ }+ })+ });++ const quota = await provider.quota();+ expect(quota.total).toBe(107374182400);+ expect(quota.used).toBe(10737418240);+ expect(quota.available).toBe(96636764160);+ });++ it("executes server-side copy in Google Drive using files.copy", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ vi.spyOn(provider.resolver, "resolveFileId").mockResolvedValueOnce("source-file-123");+ vi.spyOn(provider.resolver, "resolveParentFolderId").mockResolvedValueOnce("target-parent-456");+ vi.spyOn(provider.http, "copyFile").mockResolvedValueOnce({+ id: "copied-file-789",+ name: "report_copy.pdf"+ });++ await provider.copy("docs/report.pdf", "archive/report_copy.pdf");++ expect(provider.http.copyFile).toHaveBeenCalledWith(+ "source-file-123",+ "report_copy.pdf",+ "target-parent-456"+ );+ });++ it("executes server-side move in Google Drive using parent swapping", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ vi.spyOn(provider.resolver, "resolveFileId").mockResolvedValueOnce("file-to-move-123");+ vi.spyOn(provider.resolver, "resolveParentFolderId")+ .mockResolvedValueOnce("old-parent-111")+ .mockResolvedValueOnce("new-parent-222");+ vi.spyOn(provider.http, "moveFile").mockResolvedValueOnce({+ id: "file-to-move-123",+ name: "moved_report.pdf"+ });++ await provider.move("inbox/moved_report.pdf", "processed/moved_report.pdf");++ expect(provider.http.moveFile).toHaveBeenCalledWith(+ "file-to-move-123",+ "new-parent-222",+ "old-parent-111",+ "moved_report.pdf"+ );+ });+});diff --git a/packages/google-drive/tests/api/http.test.ts b/packages/google-drive/tests/api/http.test.tsnew file mode 100644index 0000000..67bafbb--- /dev/null+++ b/packages/google-drive/tests/api/http.test.ts@@ -0,0 +1,105 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { DriveHttpClient } from "../../src/api/http.js";+import { GoogleOAuthClient } from "../../src/auth/oauth-client.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("DriveHttpClient", () => {+ const originalFetch = global.fetch;+ let oauth: GoogleOAuthClient;+ let client: DriveHttpClient;++ beforeEach(() => {+ global.fetch = vi.fn();+ oauth = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: { accessToken: "valid-bearer-token" }+ });+ client = new DriveHttpClient(oauth);+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ it("injects Authorization header into requests", async () => {+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ id: "123", name: "test.pdf" })+ });++ const file = await client.getFile("123");+ expect(file.id).toBe("123");++ expect(global.fetch).toHaveBeenCalledWith(+ expect.stringContaining("/files/123"),+ expect.objectContaining({+ headers: expect.any(Headers)+ })+ );+ });++ it("maps error responses using mapGoogleDriveError", async () => {+ (global.fetch as any).mockResolvedValueOnce({+ ok: false,+ status: 404,+ json: async () => ({+ error: {+ code: 404,+ message: "File not found",+ errors: [{ reason: "notFound" }]+ }+ })+ });++ await expect(client.getFile("missing-id")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.OBJECT_NOT_FOUND+ })+ );+ });++ it("creates folders with folder mimeType", async () => {+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ id: "folder-456",+ name: "MyFolder",+ mimeType: "application/vnd.google-apps.folder"+ })+ });++ const folder = await client.createFolder("MyFolder", "parent-123");+ expect(folder.id).toBe("folder-456");+ expect(global.fetch).toHaveBeenCalledWith(+ expect.stringContaining("/files"),+ expect.objectContaining({+ method: "POST",+ body: JSON.stringify({+ name: "MyFolder",+ mimeType: "application/vnd.google-apps.folder",+ parents: ["parent-123"]+ })+ })+ );+ });++ it("queries storage quota accurately", async () => {+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ storageQuota: {+ limit: "15000000000",+ usage: "5000000000"+ }+ })+ });++ const about = await client.getAboutQuota();+ expect(about.storageQuota?.limit).toBe("15000000000");+ expect(about.storageQuota?.usage).toBe("5000000000");+ });+});diff --git a/packages/google-drive/tests/api/multipart.test.ts b/packages/google-drive/tests/api/multipart.test.tsnew file mode 100644index 0000000..bd6012d--- /dev/null+++ b/packages/google-drive/tests/api/multipart.test.ts@@ -0,0 +1,34 @@+import { describe, it, expect } from "vitest";+import { buildMultipartBody, storageInputToUint8Array } from "../../src/api/multipart.js";+import { Readable } from "node:stream";++describe("Multipart Upload Payload Builder", () => {+ it("converts string, Uint8Array, Buffer, and Stream to Uint8Array", async () => {+ const fromStr = await storageInputToUint8Array("hello");+ expect(new TextDecoder().decode(fromStr)).toBe("hello");++ const fromBuf = await storageInputToUint8Array(Buffer.from("buffer data"));+ expect(new TextDecoder().decode(fromBuf)).toBe("buffer data");++ const fromStream = await storageInputToUint8Array(Readable.from(["stream ", "chunks"]));+ expect(new TextDecoder().decode(fromStream)).toBe("stream chunks");+ });++ it("constructs valid multipart/related payload with boundary and headers", async () => {+ const metadata = { name: "test-file.txt", parents: ["folder123"] };+ const content = "Hello Google Drive from BYOC!";+ const mimeType = "text/plain";++ const payload = await buildMultipartBody(metadata, content, mimeType);++ expect(payload.contentType).toMatch(/^multipart\/related; boundary=-------BYOC_BOUNDARY_/);+ expect(payload.body).toBeInstanceOf(Uint8Array);++ const bodyText = new TextDecoder().decode(payload.body);+ expect(bodyText).toContain('Content-Type: application/json; charset=UTF-8');+ expect(bodyText).toContain('"name":"test-file.txt"');+ expect(bodyText).toContain('"parents":["folder123"]');+ expect(bodyText).toContain('Content-Type: text/plain');+ expect(bodyText).toContain('Hello Google Drive from BYOC!');+ });+});diff --git a/packages/google-drive/tests/api/resumable.test.ts b/packages/google-drive/tests/api/resumable.test.tsnew file mode 100644index 0000000..570611f--- /dev/null+++ b/packages/google-drive/tests/api/resumable.test.ts@@ -0,0 +1,117 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { ResumableUploader, GOOGLE_DRIVE_CHUNK_ALIGNMENT } from "../../src/api/resumable.js";+import { GoogleOAuthClient } from "../../src/auth/oauth-client.js";++describe("ResumableUploader", () => {+ const originalFetch = global.fetch;+ let oauth: GoogleOAuthClient;+ let uploader: ResumableUploader;++ beforeEach(() => {+ global.fetch = vi.fn();+ oauth = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ });+ uploader = new ResumableUploader(oauth);+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ it("initiates upload session and transmits chunks to completion", async () => {+ const sessionUri = "https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=session123";++ // 1. Session initiation response+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ headers: new Headers({ Location: sessionUri })+ });++ // Create 512 KiB data payload (2 * 256 KiB chunks)+ const payload = new Uint8Array(GOOGLE_DRIVE_CHUNK_ALIGNMENT * 2);+ payload.fill(65); // Fill with 'A'++ // 2. Chunk 1 PUT response -> 308 Resume Incomplete+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 308,+ headers: new Headers({ Range: `bytes=0-${GOOGLE_DRIVE_CHUNK_ALIGNMENT - 1}` })+ });++ // 3. Chunk 2 PUT response -> 200 Complete+ const finalResource = {+ id: "final-gdrive-file-id",+ name: "big-file.bin",+ size: String(payload.byteLength),+ mimeType: "application/octet-stream"+ };++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => finalResource+ });++ const progressEvents: any[] = [];++ const result = await uploader.upload(+ { name: "big-file.bin" },+ payload,+ {+ chunkSize: GOOGLE_DRIVE_CHUNK_ALIGNMENT,+ onProgress: (p) => progressEvents.push(p)+ }+ );++ expect(result.id).toBe("final-gdrive-file-id");+ expect(progressEvents.length).toBe(2);+ expect(progressEvents[0]?.percentage).toBe(50);+ expect(progressEvents[1]?.percentage).toBe(100);++ // Verify initiation headers+ expect(global.fetch).toHaveBeenNthCalledWith(+ 1,+ expect.stringContaining("uploadType=resumable"),+ expect.objectContaining({+ method: "POST",+ headers: expect.any(Headers)+ })+ );++ // Verify chunk 1 headers+ expect(global.fetch).toHaveBeenNthCalledWith(+ 2,+ sessionUri,+ expect.objectContaining({+ method: "PUT",+ headers: {+ "Content-Type": "application/octet-stream",+ "Content-Range": `bytes 0-${GOOGLE_DRIVE_CHUNK_ALIGNMENT - 1}/${payload.byteLength}`+ }+ })+ );+ });++ it("handles 0-byte empty file upload", async () => {+ const sessionUri = "https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=empty123";++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ headers: new Headers({ Location: sessionUri })+ });++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ id: "empty-file-id", name: "empty.txt", size: "0" })+ });++ const result = await uploader.upload({ name: "empty.txt" }, "");+ expect(result.id).toBe("empty-file-id");+ });+});diff --git a/packages/google-drive/tests/auth/oauth-client.test.ts b/packages/google-drive/tests/auth/oauth-client.test.tsnew file mode 100644index 0000000..cfbc049--- /dev/null+++ b/packages/google-drive/tests/auth/oauth-client.test.ts@@ -0,0 +1,190 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { GoogleOAuthClient } from "../../src/auth/oauth-client.js";+import { GoogleDriveScope } from "../../src/auth/types.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("GoogleOAuthClient", () => {+ const originalFetch = global.fetch;++ beforeEach(() => {+ global.fetch = vi.fn();+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ it("throws StorageError if clientId is missing", () => {+ expect(() => new GoogleOAuthClient({} as any)).toThrowError(StorageError);+ });++ it("constructs compliant Google OAuth authorization URL", () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id.apps.googleusercontent.com",+ redirectUri: "http://localhost:3000/callback"+ });++ const url = client.getAuthorizationUrl({+ state: "csrf-state-123",+ codeChallenge: "challenge-xyz",+ scopes: [GoogleDriveScope.FILE]+ });++ const parsed = new URL(url);+ expect(parsed.origin).toBe("https://accounts.google.com");+ expect(parsed.pathname).toBe("/o/oauth2/v2/auth");+ expect(parsed.searchParams.get("client_id")).toBe("test-client-id.apps.googleusercontent.com");+ expect(parsed.searchParams.get("redirect_uri")).toBe("http://localhost:3000/callback");+ expect(parsed.searchParams.get("response_type")).toBe("code");+ expect(parsed.searchParams.get("scope")).toBe("https://www.googleapis.com/auth/drive.file");+ expect(parsed.searchParams.get("access_type")).toBe("offline");+ expect(parsed.searchParams.get("state")).toBe("csrf-state-123");+ expect(parsed.searchParams.get("code_challenge")).toBe("challenge-xyz");+ expect(parsed.searchParams.get("code_challenge_method")).toBe("S256");+ });++ it("exchanges authorization code for access and refresh tokens", async () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id",+ clientSecret: "test-client-secret",+ redirectUri: "http://localhost:3000/callback"+ });++ const mockTokenResponse = {+ access_token: "mock-access-token-123",+ refresh_token: "mock-refresh-token-456",+ token_type: "Bearer",+ expires_in: 3600,+ scope: "https://www.googleapis.com/auth/drive.file"+ };++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ json: async () => mockTokenResponse+ });++ const session = await client.exchangeCode({+ code: "auth-code-789",+ codeVerifier: "code-verifier-abc"+ });++ expect(session.accessToken).toBe("mock-access-token-123");+ expect(session.refreshToken).toBe("mock-refresh-token-456");+ expect(session.expiresAt).toBeDefined();++ // Verify session stored+ const activeSession = await client.storage.get();+ expect(activeSession?.accessToken).toBe("mock-access-token-123");+ });++ it("returns active access token if still valid", async () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: {+ accessToken: "valid-token-abc",+ expiresAt: Date.now() + 1000 * 60 * 30 // 30 mins remaining+ }+ });++ const token = await client.getAccessToken();+ expect(token).toBe("valid-token-abc");+ expect(global.fetch).not.toHaveBeenCalled();+ });++ it("automatically refreshes token when expired", async () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: {+ accessToken: "expired-token-old",+ refreshToken: "valid-refresh-token",+ expiresAt: Date.now() - 1000 * 60 // expired 1 minute ago+ }+ });++ const mockRefreshResponse = {+ access_token: "new-fresh-access-token",+ token_type: "Bearer",+ expires_in: 3600+ };++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ json: async () => mockRefreshResponse+ });++ const token = await client.getAccessToken();+ expect(token).toBe("new-fresh-access-token");+ expect(global.fetch).toHaveBeenCalledTimes(1);++ const stored = await client.storage.get();+ expect(stored?.accessToken).toBe("new-fresh-access-token");+ expect(stored?.refreshToken).toBe("valid-refresh-token"); // Preserved+ });++ it("throws TOKEN_EXPIRED if expired and no refresh token is present", async () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: {+ accessToken: "expired-token-old",+ expiresAt: Date.now() - 1000 * 60+ }+ });++ await expect(client.getAccessToken()).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.TOKEN_EXPIRED+ })+ );+ });++ it("revokes token and clears session on revoke()", async () => {+ const client = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: {+ accessToken: "token-to-revoke",+ refreshToken: "refresh-to-revoke"+ }+ });++ (global.fetch as any).mockResolvedValueOnce({ ok: true });++ await client.revoke();+ expect(global.fetch).toHaveBeenCalledWith(+ expect.stringContaining("https://oauth2.googleapis.com/revoke?token=refresh-to-revoke"),+ expect.any(Object)+ );++ const session = await client.storage.get();+ expect(session).toBeNull();+ });++ it("stores and decrypts session using EncryptedFileTokenStorage (Bug #13 recipe)", async () => {+ const { EncryptedFileTokenStorage } = await import("../../src/auth/storage.js");+ const os = await import("node:os");+ const path = await import("node:path");++ const tempPath = path.join(os.tmpdir(), `byoc-token-test-${Date.now()}.json`);+ const storage = new EncryptedFileTokenStorage({+ filePath: tempPath,+ encryptionKey: "my-secure-app-secret-password-1234"+ });++ const mockSession = {+ accessToken: "secret-access-token-777",+ refreshToken: "secret-refresh-token-888",+ expiresAt: Date.now() + 3600 * 1000+ };++ storage.set(mockSession);++ // Read back and decrypt+ const restored = storage.get();+ expect(restored?.accessToken).toBe("secret-access-token-777");+ expect(restored?.refreshToken).toBe("secret-refresh-token-888");++ // Clean up+ storage.clear();+ expect(storage.get()).toBeNull();+ });+});diff --git a/packages/google-drive/tests/auth/pkce.test.ts b/packages/google-drive/tests/auth/pkce.test.tsnew file mode 100644index 0000000..3223b29--- /dev/null+++ b/packages/google-drive/tests/auth/pkce.test.ts@@ -0,0 +1,40 @@+import { describe, it, expect } from "vitest";+import {+ generateCodeVerifier,+ generateCodeChallenge,+ generateOAuthState+} from "../../src/auth/pkce.js";++describe("PKCE Utilities", () => {+ it("generates a random code_verifier of specified length", () => {+ const verifier = generateCodeVerifier(64);+ expect(typeof verifier).toBe("string");+ expect(verifier.length).toBe(64);+ // Base64url character set check+ expect(/^[A-Za-z0-9_-]+$/.test(verifier)).toBe(true);+ });++ it("clamps code_verifier length between 43 and 128 (RFC 7636)", () => {+ const shortVerifier = generateCodeVerifier(10);+ expect(shortVerifier.length).toBe(43);++ const longVerifier = generateCodeVerifier(200);+ expect(longVerifier.length).toBe(128);+ });++ it("generates deterministic SHA-256 S256 code_challenge", async () => {+ const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";+ const challenge = await generateCodeChallenge(verifier);+ expect(typeof challenge).toBe("string");+ expect(challenge.length).toBeGreaterThan(20);+ expect(/^[A-Za-z0-9_-]+$/.test(challenge)).toBe(true);+ });++ it("generates random CSRF state string", () => {+ const state1 = generateOAuthState(32);+ const state2 = generateOAuthState(32);+ expect(state1.length).toBe(32);+ expect(state2.length).toBe(32);+ expect(state1).not.toBe(state2);+ });+});diff --git a/packages/google-drive/tests/errors/mapper.test.ts b/packages/google-drive/tests/errors/mapper.test.tsnew file mode 100644index 0000000..e16a747--- /dev/null+++ b/packages/google-drive/tests/errors/mapper.test.ts@@ -0,0 +1,137 @@+import { describe, it, expect } from "vitest";+import { mapGoogleDriveError } from "../../src/errors/mapper.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("Google Drive Error Mapper", () => {+ it("passes through existing StorageError unmodified", () => {+ const original = new StorageError({+ code: BYOCErrorCode.AUTH_REQUIRED,+ message: "Already mapped",+ provider: "google-drive"+ });+ const mapped = mapGoogleDriveError(original);+ expect(mapped).toBe(original);+ });++ it("maps 401 and authError to BYOC_AUTH_REQUIRED", () => {+ const googleErr = {+ status: 401,+ response: {+ data: {+ error: {+ code: 401,+ message: "Invalid Credentials",+ errors: [{ reason: "authError" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(googleErr);+ expect(err).toBeInstanceOf(StorageError);+ expect(err.code).toBe(BYOCErrorCode.AUTH_REQUIRED);+ expect(err.statusCode).toBe(401);+ expect(err.retryable).toBe(false);+ expect(err.provider).toBe("google-drive");+ });++ it("maps storage quota exceeded to BYOC_QUOTA_EXCEEDED", () => {+ const quotaErr = {+ status: 403,+ response: {+ data: {+ error: {+ code: 403,+ message: "The user's Drive storage quota has been exceeded.",+ errors: [{ reason: "storageQuotaExceeded" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(quotaErr);+ expect(err.code).toBe(BYOCErrorCode.QUOTA_EXCEEDED);+ expect(err.statusCode).toBe(403);+ expect(err.retryable).toBe(false);+ });++ it("maps 429 rate limit exceeded to BYOC_RATE_LIMITED with retryable=true", () => {+ const rateLimitErr = {+ status: 429,+ response: {+ data: {+ error: {+ code: 429,+ message: "User Rate Limit Exceeded",+ errors: [{ reason: "userRateLimitExceeded" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(rateLimitErr);+ expect(err.code).toBe(BYOCErrorCode.RATE_LIMITED);+ expect(err.statusCode).toBe(429);+ expect(err.retryable).toBe(true);+ });++ it("maps 404 notFound to BYOC_OBJECT_NOT_FOUND", () => {+ const notFoundErr = {+ status: 404,+ response: {+ data: {+ error: {+ code: 404,+ message: "File not found: abc123",+ errors: [{ reason: "notFound" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(notFoundErr);+ expect(err.code).toBe(BYOCErrorCode.OBJECT_NOT_FOUND);+ expect(err.statusCode).toBe(404);+ expect(err.retryable).toBe(false);+ });++ it("maps 503 backendError to BYOC_PROVIDER_UNAVAILABLE with retryable=true", () => {+ const backendErr = {+ status: 503,+ response: {+ data: {+ error: {+ code: 503,+ message: "Backend Error",+ errors: [{ reason: "backendError" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(backendErr);+ expect(err.code).toBe(BYOCErrorCode.PROVIDER_UNAVAILABLE);+ expect(err.statusCode).toBe(503);+ expect(err.retryable).toBe(true);+ });++ it("maps 403 forbidden to BYOC_PERMISSION_DENIED", () => {+ const forbiddenErr = {+ status: 403,+ response: {+ data: {+ error: {+ code: 403,+ message: "The caller does not have permission",+ errors: [{ reason: "forbidden" }]+ }+ }+ }+ };++ const err = mapGoogleDriveError(forbiddenErr);+ expect(err.code).toBe(BYOCErrorCode.PERMISSION_DENIED);+ expect(err.statusCode).toBe(403);+ expect(err.retryable).toBe(false);+ });+});diff --git a/packages/google-drive/tests/hardening/failure-injection.test.ts b/packages/google-drive/tests/hardening/failure-injection.test.tsnew file mode 100644index 0000000..a545a49--- /dev/null+++ b/packages/google-drive/tests/hardening/failure-injection.test.ts@@ -0,0 +1,141 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { GoogleDriveProvider } from "../../src/adapter.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("Failure Injection & Hardening Test Suite", () => {+ const originalFetch = global.fetch;++ beforeEach(() => {+ global.fetch = vi.fn();+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ it("recovers from transient 429 rate limits via backoff and succeeds", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ // 1. Root folder query -> found+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ files: [{ id: "root-folder-id" }] })+ });++ // 2. Upload attempt 1 -> 429 Rate Limit+ (global.fetch as any).mockResolvedValueOnce({+ ok: false,+ status: 429,+ json: async () => ({+ error: { code: 429, message: "Rate limit exceeded", errors: [{ reason: "rateLimitExceeded" }] }+ })+ });++ // 3. Upload attempt 2 -> 200 Success+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ id: "recovered-file-id",+ name: "resilient.pdf",+ mimeType: "application/pdf"+ })+ });++ const result = await provider.upload("resilient.pdf", "PDF Data");+ expect(result.id).toBe("gdrive_recovered-file-id");+ expect(global.fetch).toHaveBeenCalledTimes(3);+ });++ it("fails immediately on 403 quota exceeded without wasting retries", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ }+ });++ // 1. Root folder query -> found+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({ files: [{ id: "root-folder-id" }] })+ });++ // 2. Upload attempt -> 403 Quota Exceeded+ (global.fetch as any).mockResolvedValueOnce({+ ok: false,+ status: 403,+ json: async () => ({+ error: {+ code: 403,+ message: "User storage quota exceeded",+ errors: [{ reason: "storageQuotaExceeded" }]+ }+ })+ });++ await expect(provider.upload("large.zip", "data")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.QUOTA_EXCEEDED,+ retryable: false+ })+ );++ // Ensure it did not retry on quota error+ expect(global.fetch).toHaveBeenCalledTimes(2);+ });++ it("transparently refreshes expired token during operation", async () => {+ const provider = new GoogleDriveProvider({+ auth: {+ clientId: "test-client-id",+ session: {+ accessToken: "expired-token-123",+ refreshToken: "valid-refresh-token",+ expiresAt: Date.now() - 1000 * 60 // Expired 1 min ago+ }+ }+ });++ // 1. OAuth refresh endpoint call+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ access_token: "new-fresh-access-token",+ expires_in: 3600+ })+ });++ // 2. Metadata getFile query using fresh token+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ json: async () => ({+ id: "meta-id-123",+ name: "file.txt",+ mimeType: "text/plain"+ })+ });++ // Setup cached file ID so resolveFileId doesn't query root folder+ await provider.resolver.setCached("file.txt", "meta-id-123");++ const meta = await provider.metadata("file.txt");+ expect(meta.id).toBe("gdrive_meta-id-123");++ // Verify fresh token was requested+ expect(global.fetch).toHaveBeenCalledWith(+ expect.stringContaining("https://oauth2.googleapis.com/token"),+ expect.any(Object)+ );+ });+});diff --git a/packages/google-drive/tests/paths/virtual-path.test.ts b/packages/google-drive/tests/paths/virtual-path.test.tsnew file mode 100644index 0000000..a76fb1b--- /dev/null+++ b/packages/google-drive/tests/paths/virtual-path.test.ts@@ -0,0 +1,158 @@+import { describe, it, expect, vi, beforeEach } from "vitest";+import {+ LruTtlPathCache,+ GoogleDrivePathResolver+} from "../../src/paths/virtual-path.js";+import { DriveHttpClient } from "../../src/api/http.js";+import { GoogleOAuthClient } from "../../src/auth/oauth-client.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("LruTtlPathCache", () => {+ it("stores and retrieves cached path mappings", () => {+ const cache = new LruTtlPathCache();+ cache.set("users/123/avatar.jpg", "file-id-123");+ expect(cache.get("users/123/avatar.jpg")).toBe("file-id-123");+ });++ it("returns undefined for expired entries", async () => {+ const cache = new LruTtlPathCache({ ttlMs: 10 });+ cache.set("temp/file.txt", "temp-id");++ expect(cache.get("temp/file.txt")).toBe("temp-id");++ await new Promise((resolve) => setTimeout(resolve, 20));+ expect(cache.get("temp/file.txt")).toBeUndefined();+ });++ it("evicts least recently used items when maxSize is exceeded", () => {+ const cache = new LruTtlPathCache({ maxSize: 2 });+ cache.set("path1", "id1");+ cache.set("path2", "id2");++ // Access path1 so path2 becomes the oldest+ cache.get("path1");++ // Add path3 -> should evict path2+ cache.set("path3", "id3");++ expect(cache.get("path1")).toBe("id1");+ expect(cache.get("path2")).toBeUndefined(); // Evicted+ expect(cache.get("path3")).toBe("id3");+ });++ it("deletes and clears entries cleanly", () => {+ const cache = new LruTtlPathCache();+ cache.set("a", "1");+ cache.set("b", "2");++ cache.delete("a");+ expect(cache.get("a")).toBeUndefined();+ expect(cache.get("b")).toBe("2");++ cache.clear();+ expect(cache.get("b")).toBeUndefined();+ });+});++describe("GoogleDrivePathResolver", () => {+ let oauth: GoogleOAuthClient;+ let http: DriveHttpClient;+ let cache: LruTtlPathCache;+ let resolver: GoogleDrivePathResolver;++ beforeEach(() => {+ oauth = new GoogleOAuthClient({+ clientId: "test-client-id",+ session: { accessToken: "valid-token" }+ });+ http = new DriveHttpClient(oauth);+ cache = new LruTtlPathCache();+ resolver = new GoogleDrivePathResolver(http, "MyTestApp", cache);+ });++ it("resolves or creates root folder under Drive root", async () => {+ vi.spyOn(http, "listFiles").mockResolvedValueOnce({+ kind: "drive#fileList",+ files: [{ id: "root-folder-id-789", name: "MyTestApp", mimeType: "application/vnd.google-apps.folder" }]+ });++ const rootId = await resolver.ensureRootFolder();+ expect(rootId).toBe("root-folder-id-789");+ expect(http.listFiles).toHaveBeenCalledWith(+ expect.stringContaining("name = 'MyTestApp' and 'root' in parents"),+ 1+ );++ // Second call should hit in-memory / cache without calling listFiles+ const cachedRootId = await resolver.ensureRootFolder();+ expect(cachedRootId).toBe("root-folder-id-789");+ expect(http.listFiles).toHaveBeenCalledTimes(1);+ });++ it("recursively creates intermediate folder hierarchies", async () => {+ vi.spyOn(http, "listFiles")+ // 1. Root folder check -> found+ .mockResolvedValueOnce({+ kind: "drive#fileList",+ files: [{ id: "root-id", name: "MyTestApp", mimeType: "application/vnd.google-apps.folder" }]+ })+ // 2. "users" folder check -> not found+ .mockResolvedValueOnce({ kind: "drive#fileList", files: [] })+ // 3. "123" folder check -> not found+ .mockResolvedValueOnce({ kind: "drive#fileList", files: [] });++ vi.spyOn(http, "createFolder")+ .mockResolvedValueOnce({ id: "users-folder-id", name: "users", mimeType: "application/vnd.google-apps.folder" })+ .mockResolvedValueOnce({ id: "123-folder-id", name: "123", mimeType: "application/vnd.google-apps.folder" });++ const parentId = await resolver.resolveParentFolderId("users/123/avatar.jpg");+ expect(parentId).toBe("123-folder-id");+ expect(http.createFolder).toHaveBeenCalledWith("users", "root-id");+ expect(http.createFolder).toHaveBeenCalledWith("123", "users-folder-id");+ });++ it("resolves duplicate filenames deterministically by choosing newest modifiedTime", async () => {+ vi.spyOn(resolver, "resolveParentFolderId").mockResolvedValue("parent-folder-id");++ vi.spyOn(http, "listFiles").mockResolvedValueOnce({+ kind: "drive#fileList",+ files: [+ { id: "old-file-id", name: "report.pdf", mimeType: "application/pdf", modifiedTime: "2026-01-01T00:00:00Z" },+ { id: "new-file-id", name: "report.pdf", mimeType: "application/pdf", modifiedTime: "2026-08-01T00:00:00Z" }+ ]+ });++ const resolvedId = await resolver.resolveFileId("documents/report.pdf");+ expect(resolvedId).toBe("new-file-id");+ });++ it("throws OBJECT_NOT_FOUND if file is missing and invalidates cache", async () => {+ vi.spyOn(resolver, "resolveParentFolderId").mockResolvedValue("parent-folder-id");+ vi.spyOn(http, "listFiles").mockResolvedValueOnce({+ kind: "drive#fileList",+ files: []+ });++ await expect(resolver.resolveFileId("missing.txt")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.OBJECT_NOT_FOUND+ })+ );+ });++ it("safely escapes single quotes and backslashes in filenames (Bug #5 fix)", async () => {+ vi.spyOn(resolver, "resolveParentFolderId").mockResolvedValue("parent-folder-id");+ vi.spyOn(http, "listFiles").mockResolvedValueOnce({+ kind: "drive#fileList",+ files: [{ id: "bob-file-id", name: "Bob's Resume.pdf", mimeType: "application/pdf" }]+ });++ const fileId = await resolver.resolveFileId("documents/Bob's Resume.pdf");+ expect(fileId).toBe("bob-file-id");++ expect(http.listFiles).toHaveBeenCalledWith(+ expect.stringContaining("name = 'Bob\\'s Resume.pdf' and 'parent-folder-id' in parents"),+ 10+ );+ });+});diff --git a/packages/google-drive/tsconfig.json b/packages/google-drive/tsconfig.jsonnew file mode 100644index 0000000..1d4b6dc--- /dev/null+++ b/packages/google-drive/tsconfig.json@@ -0,0 +1,12 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": "src",+ "outDir": "dist",+ "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"+ },+ "references": [+ { "path": "../core" }+ ],+ "include": ["src/**/*"]+}diff --git a/packages/provider-sdk/LICENSE b/packages/provider-sdk/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/packages/provider-sdk/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/packages/provider-sdk/README.md b/packages/provider-sdk/README.mdnew file mode 100644index 0000000..8ff52da--- /dev/null+++ b/packages/provider-sdk/README.md@@ -0,0 +1,69 @@+# @byoc/provider-sdk++Certification suite for **BYOC (Bring Your Own Cloud)** provider adapters: verify that a custom storage adapter behaves the way `@byoc/core` expects before you ship it.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Requires `@byoc/core`.+>+> **Status: v0.2.0.**++## Install++```bash+npm install --save-dev @byoc/provider-sdk+```++## Usage++Point the suite at a factory that returns your adapter. It exercises the full `BYOCProvider` contract against a live instance and returns a structured report.++```ts+import { runProviderComplianceSuite } from "@byoc/provider-sdk";+import { MyCustomProvider } from "./my-provider.js";++const report = await runProviderComplianceSuite(+ () => new MyCustomProvider({ /* ... */ })+);++console.log(`${report.passed}/${report.total} passed`);++for (const result of report.results) {+ if (!result.passed) console.error(`✗ ${result.name}: ${result.error}`);+}+```++Adapters that legitimately lack a capability can skip those assertions:++```ts+await runProviderComplianceSuite(factory, {+ skipQuota: true, // provider has no quota concept (e.g. S3)+ skipFolders: true // provider has no explicit folders+});+```++## What it checks++Manifest structure, capability declarations, the connect/disconnect lifecycle, upload and download round-trips, metadata and `exists()` accuracy, listing, deletion, and correct `StorageError` codes for missing objects and unsupported capabilities.++## Report shape++```ts+interface ComplianceReport {+ providerId: string;+ providerName: string;+ total: number;+ passed: number;+ failed: number;+ results: Array<{+ name: string;+ passed: boolean;+ error?: string;+ durationMs: number;+ }>;+}+```++The suite catches per-test failures rather than throwing, so one broken operation still produces a full report. `vitest` is an optional peer dependency; the suite runs standalone and doesn't require a test runner.++## License++[Apache-2.0](./LICENSE)diff --git a/packages/provider-sdk/package.json b/packages/provider-sdk/package.jsonnew file mode 100644index 0000000..4c43805--- /dev/null+++ b/packages/provider-sdk/package.json@@ -0,0 +1,53 @@+{+ "name": "@byoc/provider-sdk",+ "version": "0.2.1",+ "description": "BYOC Provider SDK \u2014 Certification suite and developer tools for building BYOC storage adapters",+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js",+ "default": "./dist/index.js"+ }+ },+ "scripts": {+ "build": "tsc -b",+ "clean": "rm -rf dist tsconfig.tsbuildinfo"+ },+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "keywords": [+ "byoc",+ "sdk",+ "compliance",+ "certification",+ "storage-adapter"+ ],+ "author": "Ajay Ramineni",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Ajayvarmaramineni/BYOC.git",+ "directory": "packages/provider-sdk"+ },+ "publishConfig": {+ "access": "public"+ },+ "files": [+ "dist",+ "!dist/tsconfig.tsbuildinfo",+ "README.md",+ "LICENSE"+ ],+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC/tree/main/packages/provider-sdk#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ },+ "sideEffects": false+}diff --git a/packages/provider-sdk/src/compliance.ts b/packages/provider-sdk/src/compliance.tsnew file mode 100644index 0000000..ba3b516--- /dev/null+++ b/packages/provider-sdk/src/compliance.ts@@ -0,0 +1,156 @@+import type { BYOCProvider } from "@byoc/core";+import { BYOCErrorCode, StorageError } from "@byoc/core";++export interface ComplianceSuiteOptions {+ /** Skip quota assertions if provider does not support it */+ skipQuota?: boolean;+ /** Skip folder creation assertions if provider does not support explicit folders */+ skipFolders?: boolean;+}++export interface ComplianceTestResult {+ name: string;+ passed: boolean;+ error?: string;+ durationMs: number;+}++export interface ComplianceReport {+ providerId: string;+ providerName: string;+ total: number;+ passed: number;+ failed: number;+ results: ComplianceTestResult[];+}++/**+ * Executes standard BYOC Provider Compliance & Certification Test Suite against any BYOCProvider.+ */+export async function runProviderComplianceSuite(+ providerFactory: () => Promise<BYOCProvider> | BYOCProvider,+ options: ComplianceSuiteOptions = {}+): Promise<ComplianceReport> {+ const provider = await providerFactory();+ const manifest = provider.manifest();+ const capabilities = await provider.capabilities();++ const results: ComplianceTestResult[] = [];++ async function test(name: string, fn: () => Promise<void>): Promise<void> {+ const start = Date.now();+ try {+ await fn();+ results.push({ name, passed: true, durationMs: Date.now() - start });+ } catch (err) {+ results.push({+ name,+ passed: false,+ error: err instanceof Error ? err.message : String(err),+ durationMs: Date.now() - start+ });+ }+ }++ // 1. Manifest Structure Validation+ await test("Manifest: Validates required metadata fields", async () => {+ if (!manifest.id || typeof manifest.id !== "string") throw new Error("Manifest 'id' is required.");+ if (!manifest.name || typeof manifest.name !== "string") throw new Error("Manifest 'name' is required.");+ if (!manifest.category) throw new Error("Manifest 'category' is required.");+ if (!manifest.authentication) throw new Error("Manifest 'authentication' is required.");+ });++ // 2. Capability Structure Validation+ await test("Capabilities: Declares standard boolean feature flags", async () => {+ if (typeof capabilities.folders !== "boolean") throw new Error("Capability 'folders' must be a boolean.");+ if (typeof capabilities.resumableUploads !== "boolean") throw new Error("Capability 'resumableUploads' must be a boolean.");+ if (typeof capabilities.quota !== "boolean") throw new Error("Capability 'quota' must be a boolean.");+ });++ // 3. Connect & Initialize+ await test("Lifecycle: connect() initializes without throwing", async () => {+ await provider.connect();+ });++ // 4. Basic File Upload & Verification+ const testFilename = `compliance-test-${Date.now()}.txt`;+ const testContent = "BYOC Compliance Verification Payload 12345";++ await test("Storage: upload() stores content and returns StorageObject", async () => {+ const obj = await provider.upload(testFilename, testContent, { mimeType: "text/plain" });+ if (!obj.id) throw new Error("Uploaded object must have a non-empty 'id'.");+ if (obj.name !== testFilename) throw new Error(`Expected name '${testFilename}', received '${obj.name}'`);+ if (obj.provider !== manifest.id) throw new Error(`Expected provider '${manifest.id}', received '${obj.provider}'`);+ });++ // 5. Download & Content Verification+ await test("Storage: download() returns valid text and metadata", async () => {+ const output = await provider.download(testFilename);+ const text = await output.text();+ if (text !== testContent) throw new Error(`Downloaded content '${text}' did not match original '${testContent}'`);+ if (output.metadata.name !== testFilename) throw new Error("Metadata mismatch on download.");+ });++ // 6. Metadata Inspection+ await test("Storage: metadata() returns accurate properties", async () => {+ const meta = await provider.metadata(testFilename);+ if (meta.name !== testFilename) throw new Error("metadata() returned incorrect file name.");+ });++ // 7. Existence Check+ await test("Storage: exists() returns true for present files and false for missing files", async () => {+ const existsPresent = await provider.exists(testFilename);+ if (!existsPresent) throw new Error("exists() returned false for an uploaded file.");++ const existsMissing = await provider.exists(`missing-file-${Date.now()}.bin`);+ if (existsMissing) throw new Error("exists() returned true for a nonexistent file.");+ });++ // 8. Error Mapping on Missing Object+ await test("Storage: download() on missing file throws OBJECT_NOT_FOUND StorageError", async () => {+ try {+ await provider.download(`nonexistent-${Date.now()}.txt`);+ throw new Error("download() did not throw on missing file.");+ } catch (err) {+ if (!StorageError.isStorageError(err) || err.code !== BYOCErrorCode.OBJECT_NOT_FOUND) {+ throw new Error(`Expected StorageError with code OBJECT_NOT_FOUND, received: ${err}`);+ }+ }+ });++ // 9. Deletion & Post-Deletion Check+ await test("Storage: delete() removes the file cleanly", async () => {+ await provider.delete(testFilename);+ const exists = await provider.exists(testFilename);+ if (exists) throw new Error("exists() returned true after delete().");+ });++ // 10. Folder Operations (if supported)+ if (capabilities.folders && !options.skipFolders && provider.createFolder) {+ const folderPath = `test-dir-${Date.now()}`;+ await test("Folders: createFolder() creates a folder node", async () => {+ const folder = await provider.createFolder!(folderPath);+ if (folder.type !== "folder") throw new Error("createFolder() must return type 'folder'.");+ });+ }++ // 11. Quota Operations (if supported)+ if (capabilities.quota && !options.skipQuota && provider.quota) {+ await test("Quota: quota() returns total and used metrics", async () => {+ const q = await provider.quota!();+ if (q.used < 0) throw new Error("Quota 'used' must be non-negative.");+ });+ }++ const passed = results.filter((r) => r.passed).length;+ const failed = results.filter((r) => !r.passed).length;++ return {+ providerId: manifest.id,+ providerName: manifest.name,+ total: results.length,+ passed,+ failed,+ results+ };+}diff --git a/packages/provider-sdk/src/index.ts b/packages/provider-sdk/src/index.tsnew file mode 100644index 0000000..1d49356--- /dev/null+++ b/packages/provider-sdk/src/index.ts@@ -0,0 +1,6 @@+export {+ runProviderComplianceSuite,+ type ComplianceSuiteOptions,+ type ComplianceTestResult,+ type ComplianceReport+} from "./compliance.js";diff --git a/packages/provider-sdk/tests/compliance.test.ts b/packages/provider-sdk/tests/compliance.test.tsnew file mode 100644index 0000000..5dbe9f1--- /dev/null+++ b/packages/provider-sdk/tests/compliance.test.ts@@ -0,0 +1,81 @@+import { describe, it, expect } from "vitest";+import { runProviderComplianceSuite } from "../src/compliance.js";+import type { BYOCProvider } from "@byoc/core";+import { StorageError, BYOCErrorCode } from "@byoc/core";++describe("Provider Certification SDK & Compliance Runner", () => {+ it("certifies a valid in-memory mock provider with 100% pass rate", async () => {+ const memoryFiles = new Map<string, { content: string; mimeType?: string }>();++ const mockProvider: BYOCProvider = {+ manifest: () => ({+ id: "in-memory-test",+ name: "In-Memory Test Adapter",+ category: "self-hosted",+ authentication: "api-key",+ supportsUserOwnedStorage: true,+ adapterVersion: "1.0.0"+ }),+ capabilities: () => ({+ folders: true,+ sharing: false,+ publicUrls: false,+ resumableUploads: false,+ versioning: false,+ quota: true,+ serverSideCopy: false+ }),+ connect: async () => {},+ disconnect: async () => {},+ upload: async (path, data, options) => {+ memoryFiles.set(path, { content: String(data), mimeType: options?.mimeType });+ return {+ id: `mem_${path}`,+ path,+ name: path,+ provider: "in-memory-test",+ providerId: path+ };+ },+ download: async (path) => {+ const item = memoryFiles.get(path);+ if (!item) {+ throw new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: `File not found: ${path}`,+ provider: "in-memory-test"+ });+ }+ return {+ stream: null as any,+ text: async () => item.content,+ arrayBuffer: async () => new TextEncoder().encode(item.content).buffer,+ metadata: { id: `mem_${path}`, path, name: path, provider: "in-memory-test", providerId: path }+ };+ },+ delete: async (path) => {+ memoryFiles.delete(path);+ },+ list: async () => [],+ exists: async (path) => memoryFiles.has(path),+ metadata: async (path) => {+ const item = memoryFiles.get(path);+ if (!item) throw new StorageError({ code: BYOCErrorCode.OBJECT_NOT_FOUND, message: "Not found", provider: "in-memory-test" });+ return { id: `mem_${path}`, path, name: path, provider: "in-memory-test", providerId: path };+ },+ createFolder: async (path) => ({+ id: `folder_${path}`,+ path,+ name: path,+ provider: "in-memory-test",+ providerId: path,+ type: "folder"+ }),+ quota: async () => ({ total: 1000, used: 100, available: 900 })+ };++ const report = await runProviderComplianceSuite(() => mockProvider);+ expect(report.passed).toBe(report.total);+ expect(report.failed).toBe(0);+ });+});diff --git a/packages/provider-sdk/tsconfig.json b/packages/provider-sdk/tsconfig.jsonnew file mode 100644index 0000000..134f8ff--- /dev/null+++ b/packages/provider-sdk/tsconfig.json@@ -0,0 +1,13 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": "src",+ "outDir": "dist",+ "composite": true,+ "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"+ },+ "references": [+ { "path": "../core" }+ ],+ "include": ["src/**/*"]+}diff --git a/packages/s3-compatible/LICENSE b/packages/s3-compatible/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/packages/s3-compatible/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/packages/s3-compatible/README.md b/packages/s3-compatible/README.mdnew file mode 100644index 0000000..b5254e6--- /dev/null+++ b/packages/s3-compatible/README.md@@ -0,0 +1,64 @@+# @byoc/s3-compatible++S3-compatible provider adapter for **BYOC (Bring Your Own Cloud)**: Cloudflare R2, AWS S3, MinIO, Wasabi, and any other S3 API-compatible endpoint.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Requires `@byoc/core`.+>+> **Status: v0.2.0.** Unit tested, and validated against a live MinIO server in CI.++## Install++```bash+npm install @byoc/core @byoc/s3-compatible+```++## Usage++```ts+import { BYOC } from "@byoc/core";+import { S3CompatibleProvider } from "@byoc/s3-compatible";++const storage = new BYOC({+ provider: new S3CompatibleProvider({+ endpoint: "https://<account_id>.r2.cloudflarestorage.com",+ bucket: "user-assets",+ region: "auto",+ accessKeyId: process.env.R2_ACCESS_KEY_ID!,+ secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,+ rootPrefix: "production/data"+ })+});++await storage.connect();+await storage.writeBuffer("images/banner.png", imageBuffer);+```++For MinIO and other path-style endpoints, set `forcePathStyle: true`.++## Presigned URLs++Hand a browser a time-limited URL without proxying bytes through your server:++```ts+import { createPresignedS3Url } from "@byoc/s3-compatible";++const url = createPresignedS3Url(config, objectUrl, {+ method: "GET",+ expiresInSeconds: 3600+});+```++## What this adapter handles++- **AWS Signature Version 4**: canonical request construction verified against AWS reference vectors, with RFC 3986 query canonicalization and case-insensitive header normalization.+- **Object key encoding**: keys containing `#`, `?`, spaces, or unicode are percent-encoded per segment, so they round-trip intact.+- **Paginated listing**: `list()` follows `IsTruncated` / `NextContinuationToken` past the 1000-key response cap.+- **Server-side copy**: `x-amz-copy-source` for same-bucket moves without transferring bytes.++## Capabilities++S3 has no native folder or quota concept, so `folders` and `quota` are reported `false`. `createFolder()` and `getQuota()` throw `CAPABILITY_UNSUPPORTED` rather than silently no-op'ing.++## License++[Apache-2.0](./LICENSE)diff --git a/packages/s3-compatible/package.json b/packages/s3-compatible/package.jsonnew file mode 100644index 0000000..b391843--- /dev/null+++ b/packages/s3-compatible/package.json@@ -0,0 +1,55 @@+{+ "name": "@byoc/s3-compatible",+ "version": "0.2.1",+ "description": "Universal S3-compatible storage adapter for Cloudflare R2, AWS S3, MinIO, and Wasabi",+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js",+ "default": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "!dist/tsconfig.tsbuildinfo",+ "README.md",+ "LICENSE"+ ],+ "scripts": {+ "build": "tsc -b",+ "clean": "rm -rf dist tsconfig.tsbuildinfo"+ },+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "keywords": [+ "byoc",+ "s3",+ "cloudflare-r2",+ "minio",+ "wasabi",+ "aws-s3",+ "cloud-storage"+ ],+ "author": "Ajay Ramineni",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Ajayvarmaramineni/BYOC.git",+ "directory": "packages/s3-compatible"+ },+ "publishConfig": {+ "access": "public"+ },+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC/tree/main/packages/s3-compatible#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ },+ "sideEffects": false+}diff --git a/packages/s3-compatible/src/adapter.ts b/packages/s3-compatible/src/adapter.tsnew file mode 100644index 0000000..8abb1fa--- /dev/null+++ b/packages/s3-compatible/src/adapter.ts@@ -0,0 +1,188 @@+import type {+ BYOCProvider,+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ UploadOptions,+ BackupOptions+} from "@byoc/core";+import {+ BYOCErrorCode,+ StorageError,+ normalizeVirtualPath+} from "@byoc/core";+import { S3HttpClient, type S3ClientConfig } from "./api/client.js";+import type { PresignUrlOptions } from "./auth/signer.js";++export interface S3ProviderConfig extends S3ClientConfig {+ rootPrefix?: string;+}++/**+ * S3CompatibleProvider — Multi-cloud adapter for AWS S3, Cloudflare R2, MinIO, and Wasabi.+ */+export class S3CompatibleProvider implements BYOCProvider {+ public readonly http: S3HttpClient;+ public readonly rootPrefix: string;++ constructor(public readonly config: S3ProviderConfig) {+ if (!config || !config.endpoint || !config.bucket || !config.accessKeyId || !config.secretAccessKey) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "S3CompatibleProvider requires endpoint, bucket, accessKeyId, and secretAccessKey.",+ provider: "s3-compatible",+ retryable: false+ });+ }++ this.rootPrefix = config.rootPrefix ? normalizeVirtualPath(config.rootPrefix) : "";+ this.http = new S3HttpClient(config);+ }++ public manifest(): ProviderManifest {+ return {+ id: "s3-compatible",+ name: "S3 Compatible (R2/AWS/MinIO)",+ category: "developer-cloud",+ authentication: "access-key",+ supportsUserOwnedStorage: false,+ adapterVersion: "0.2.0"+ };+ }++ public capabilities(): ProviderCapabilities {+ return {+ folders: false,+ sharing: false,+ publicUrls: true,+ resumableUploads: false, // High-level automatic multipart orchestration is planned for v0.2.0+ versioning: true,+ quota: false,+ serverSideCopy: true+ };+ }++ public async connect(): Promise<void> {+ // S3 uses stateless SigV4 request signatures+ }++ public async disconnect(): Promise<void> {+ // Stateless+ }++ public async upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ const key = this.toKey(path);+ const result = await this.http.putObject(+ key,+ data,+ options?.mimeType,+ options?.metadata as Record<string, string>,+ options?.onProgress+ );+ return {+ ...result,+ path: normalizeVirtualPath(path)+ };+ }++ public async download(path: string): Promise<StorageOutput> {+ const key = this.toKey(path);+ const res = await this.http.getObject(key);++ return {+ stream: res.body as any,+ arrayBuffer: () => res.arrayBuffer(),+ text: () => res.text(),+ metadata: {+ id: `s3_${this.config.bucket}_${key}`,+ path: normalizeVirtualPath(path),+ name: path.split("/").pop() || path,+ provider: "s3-compatible",+ providerId: key,+ size: Number(res.headers.get("content-length")) || undefined,+ mimeType: res.headers.get("content-type") || "application/octet-stream",+ checksum: res.headers.get("etag")?.replace(/"/g, "")+ }+ };+ }++ public async delete(path: string): Promise<void> {+ const key = this.toKey(path);+ await this.http.deleteObject(key);+ }++ public async list(path?: string): Promise<StorageObject[]> {+ const key = path ? this.toKey(path) : this.rootPrefix;+ return this.http.listObjects(key, "/", this.rootPrefix);+ }++ public async exists(path: string): Promise<boolean> {+ const key = this.toKey(path);+ try {+ await this.http.headObject(key);+ return true;+ } catch (err) {+ if (StorageError.isStorageError(err) && err.code === BYOCErrorCode.OBJECT_NOT_FOUND) {+ return false;+ }+ throw err;+ }+ }++ public async metadata(path: string): Promise<StorageObject> {+ const key = this.toKey(path);+ const result = await this.http.headObject(key);+ return {+ ...result,+ path: normalizeVirtualPath(path)+ };+ }++ /**+ * Instant server-side copy within the S3 bucket using x-amz-copy-source.+ */+ public async copy(source: string, destination: string): Promise<void> {+ const sourceKey = this.toKey(source);+ const destKey = this.toKey(destination);+ await this.http.copyObject(sourceKey, destKey);+ }++ /**+ * Instant server-side move (atomic copy + delete source).+ */+ public async move(source: string, destination: string): Promise<void> {+ await this.copy(source, destination);+ await this.delete(source);+ }++ /**+ * Generates a SigV4 Presigned URL for direct secure browser client uploads or downloads.+ */+ public getSignedUrl(path: string, options?: PresignUrlOptions): string {+ const key = this.toKey(path);+ return this.http.getPresignedUrl(key, options);+ }++ public async backup(payload: StorageInput, options?: BackupOptions): Promise<StorageObject> {+ const folder = normalizeVirtualPath(options?.folder ?? "Backups");+ const filename = options?.filename ?? `backup-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;+ const targetPath = folder ? `${folder}/${filename}` : filename;++ return this.upload(targetPath, payload, {+ mimeType: options?.mimeType ?? "application/json",+ onProgress: options?.onProgress+ });+ }++ private toKey(path: string): string {+ const normalized = normalizeVirtualPath(path);+ if (!this.rootPrefix) return normalized;+ return `${this.rootPrefix}/${normalized}`;+ }+}diff --git a/packages/s3-compatible/src/api/client.ts b/packages/s3-compatible/src/api/client.tsnew file mode 100644index 0000000..5043651--- /dev/null+++ b/packages/s3-compatible/src/api/client.ts@@ -0,0 +1,583 @@+import {+ withRetry,+ StorageError,+ BYOCErrorCode,+ type StorageObject,+ type StorageInput,+ type UploadProgress+} from "@byoc/core";+import {+ signS3Request,+ createPresignedS3Url,+ rfc3986UriEncode,+ type SigV4Options,+ type PresignUrlOptions+} from "../auth/signer.js";+import { Readable } from "node:stream";++export interface S3ClientConfig extends SigV4Options {+ endpoint: string;+ bucket: string;+ forcePathStyle?: boolean;+}++export interface S3UploadPart {+ partNumber: number;+ etag: string;+}++export class S3HttpClient {+ constructor(public readonly config: S3ClientConfig) {}++ /**+ * Automatically determines whether path-style addressing is required.+ * If the endpoint hostname starts with `${bucket}.`, it is virtual-host.+ * Otherwise (e.g. s3.us-east-1.amazonaws.com, r2.cloudflarestorage.com, localhost),+ * path-style (https://<endpoint>/<bucket>/<key>) is used.+ */+ public isPathStyle(): boolean {+ if (typeof this.config.forcePathStyle === "boolean") {+ return this.config.forcePathStyle;+ }+ const host = new URL(this.config.endpoint).host.toLowerCase();+ const bucketPrefix = `${this.config.bucket.toLowerCase()}.`;+ return !host.startsWith(bucketPrefix);+ }++ public getObjectUrl(key: string): string {+ const cleanKey = key.replace(/^\/+/, "");+ const encodedKey = cleanKey+ .split("/")+ .map((segment) => rfc3986UriEncode(segment, true))+ .join("/");+ const base = this.config.endpoint.replace(/\/+$/, "");++ if (this.isPathStyle()) {+ return `${base}/${this.config.bucket}/${encodedKey}`;+ }+ return `${base}/${encodedKey}`;+ }++ public getBucketBaseUrl(): string {+ const base = this.config.endpoint.replace(/\/+$/, "");+ if (this.isPathStyle()) {+ return `${base}/${this.config.bucket}`;+ }+ return base;+ }++ public async putObject(+ key: string,+ data: StorageInput,+ mimeType?: string,+ metadata?: Record<string, string>,+ onProgress?: (progress: UploadProgress) => void+ ): Promise<StorageObject> {+ const url = this.getObjectUrl(key);+ let bodyPayload: any;+ let payloadSize: number | undefined;++ if (typeof data === "string") {+ const bytes = new TextEncoder().encode(data);+ bodyPayload = bytes;+ payloadSize = bytes.byteLength;+ } else if (data instanceof Uint8Array) {+ bodyPayload = data;+ payloadSize = data.byteLength;+ } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {+ bodyPayload = data;+ payloadSize = data.byteLength;+ } else if (data instanceof ArrayBuffer) {+ bodyPayload = new Uint8Array(data);+ payloadSize = data.byteLength;+ } else if (typeof Blob !== "undefined" && data instanceof Blob) {+ bodyPayload = data;+ payloadSize = data.size;+ } else if (+ (typeof ReadableStream !== "undefined" && data instanceof ReadableStream) ||+ (typeof Readable !== "undefined" && data instanceof Readable)+ ) {+ bodyPayload = data;+ } else {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Unsupported data payload type for S3 upload.",+ provider: "s3-compatible"+ });+ }++ const headers: Record<string, string> = {+ "content-type": mimeType || "application/octet-stream"+ };++ if (payloadSize !== undefined) {+ headers["content-length"] = String(payloadSize);+ }++ if (metadata) {+ for (const [k, v] of Object.entries(metadata)) {+ headers[`x-amz-meta-${k.toLowerCase()}`] = v;+ }+ }++ const signedHeaders = signS3Request(this.config, {+ method: "PUT",+ url,+ headers,+ body: typeof bodyPayload === "string" || bodyPayload instanceof Uint8Array ? bodyPayload : undefined+ });++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "PUT",+ headers: signedHeaders,+ body: bodyPayload,+ // @ts-ignore Node fetch streaming requires duplex: 'half'+ duplex: "half"+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ if (onProgress && payloadSize !== undefined) {+ onProgress({+ bytesUploaded: payloadSize,+ totalBytes: payloadSize,+ percentage: 100+ });+ }++ const etag = response.headers.get("etag")?.replace(/"/g, "") || undefined;++ return {+ id: `s3_${this.config.bucket}_${key}`,+ path: key,+ name: key.split("/").pop() || key,+ provider: "s3-compatible",+ providerId: key,+ size: payloadSize,+ mimeType: mimeType || "application/octet-stream",+ checksum: etag,+ updatedAt: new Date()+ };+ });+ }++ public async getObject(key: string): Promise<Response> {+ const url = this.getObjectUrl(key);+ const signedHeaders = signS3Request(this.config, {+ method: "GET",+ url+ });++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "GET",+ headers: signedHeaders+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ return response;+ });+ }++ public async deleteObject(key: string): Promise<void> {+ const url = this.getObjectUrl(key);+ const signedHeaders = signS3Request(this.config, {+ method: "DELETE",+ url+ });++ await withRetry(async () => {+ const response = await fetch(url, {+ method: "DELETE",+ headers: signedHeaders+ });++ if (!response.ok && response.status !== 404 && response.status !== 204) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ public async headObject(key: string): Promise<StorageObject> {+ const url = this.getObjectUrl(key);+ const signedHeaders = signS3Request(this.config, {+ method: "HEAD",+ url+ });++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "HEAD",+ headers: signedHeaders+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const contentLength = response.headers.get("content-length");+ const contentType = response.headers.get("content-type") || "application/octet-stream";+ const etag = response.headers.get("etag")?.replace(/"/g, "");+ const lastModified = response.headers.get("last-modified");++ return {+ id: `s3_${this.config.bucket}_${key}`,+ path: key,+ name: key.split("/").pop() || key,+ provider: "s3-compatible",+ providerId: key,+ size: contentLength ? Number(contentLength) : undefined,+ mimeType: contentType,+ checksum: etag,+ updatedAt: lastModified ? new Date(lastModified) : undefined+ };+ });+ }++ public async listObjects(prefix?: string, delimiter: string = "/", rootPrefix: string = ""): Promise<StorageObject[]> {+ const allResults: StorageObject[] = [];+ let continuationToken: string | undefined = undefined;++ do {+ const base = this.getBucketBaseUrl();+ const url = new URL(base.endsWith("/") ? base : `${base}/`);+ url.searchParams.set("list-type", "2");++ if (prefix) {+ const cleanPrefix = prefix.replace(/^\/+/, "");+ url.searchParams.set("prefix", cleanPrefix.endsWith("/") ? cleanPrefix : `${cleanPrefix}/`);+ }++ if (delimiter) {+ url.searchParams.set("delimiter", delimiter);+ }++ if (continuationToken) {+ url.searchParams.set("continuation-token", continuationToken);+ }++ const signedHeaders = signS3Request(this.config, {+ method: "GET",+ url: url.toString()+ });++ const pageXml = await withRetry(async () => {+ const response = await fetch(url.toString(), {+ method: "GET",+ headers: signedHeaders+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ return response.text();+ });++ const pageResults = parseS3ListXml(pageXml, this.config.bucket, rootPrefix);+ allResults.push(...pageResults);++ const isTruncatedMatch = pageXml.match(/<IsTruncated>(true|false)<\/IsTruncated>/i);+ const isTruncated = isTruncatedMatch ? isTruncatedMatch[1]?.toLowerCase() === "true" : false;++ if (isTruncated) {+ const tokenMatch = pageXml.match(/<NextContinuationToken>(.*?)<\/NextContinuationToken>/);+ continuationToken = tokenMatch && tokenMatch[1] ? tokenMatch[1] : undefined;+ } else {+ continuationToken = undefined;+ }+ } while (continuationToken);++ return allResults;+ }++ /**+ * Executes an instantaneous server-side copy using x-amz-copy-source.+ */+ public async copyObject(sourceKey: string, destKey: string): Promise<void> {+ const destUrl = this.getObjectUrl(destKey);+ const cleanSourceKey = sourceKey.replace(/^\/+/, "");+ const copySourceHeader = encodeURI(`/${this.config.bucket}/${cleanSourceKey}`);++ const signedHeaders = signS3Request(this.config, {+ method: "PUT",+ url: destUrl,+ headers: {+ "x-amz-copy-source": copySourceHeader+ }+ });++ await withRetry(async () => {+ const response = await fetch(destUrl, {+ method: "PUT",+ headers: signedHeaders+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ /**+ * S3 Multipart Upload: Initiate+ */+ public async createMultipartUpload(key: string, mimeType?: string): Promise<string> {+ const url = new URL(this.getObjectUrl(key));+ url.searchParams.set("uploads", "");++ const signedHeaders = signS3Request(this.config, {+ method: "POST",+ url: url.toString(),+ headers: {+ "content-type": mimeType || "application/octet-stream"+ }+ });++ return withRetry(async () => {+ const response = await fetch(url.toString(), {+ method: "POST",+ headers: signedHeaders+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const xml = await response.text();+ const match = xml.match(/<UploadId>(.*?)<\/UploadId>/);+ if (!match || !match[1]) {+ throw new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: "Failed to parse S3 Multipart UploadId response.",+ provider: "s3-compatible"+ });+ }++ return match[1];+ });+ }++ /**+ * S3 Multipart Upload: Upload a single chunk part+ */+ public async uploadPart(+ key: string,+ uploadId: string,+ partNumber: number,+ data: Uint8Array+ ): Promise<S3UploadPart> {+ const url = new URL(this.getObjectUrl(key));+ url.searchParams.set("partNumber", String(partNumber));+ url.searchParams.set("uploadId", uploadId);++ const signedHeaders = signS3Request(this.config, {+ method: "PUT",+ url: url.toString(),+ body: data+ });++ return withRetry(async () => {+ const response = await fetch(url.toString(), {+ method: "PUT",+ headers: signedHeaders,+ body: data as any+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const etag = response.headers.get("etag")?.replace(/"/g, "");+ if (!etag) {+ throw new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: `S3 UploadPart ${partNumber} did not return an ETag header.`,+ provider: "s3-compatible"+ });+ }++ return { partNumber, etag };+ });+ }++ /**+ * S3 Multipart Upload: Complete and commit parts+ */+ public async completeMultipartUpload(+ key: string,+ uploadId: string,+ parts: S3UploadPart[]+ ): Promise<StorageObject> {+ const url = new URL(this.getObjectUrl(key));+ url.searchParams.set("uploadId", uploadId);++ const sortedParts = [...parts].sort((a, b) => a.partNumber - b.partNumber);+ const xmlPayload = [+ "<CompleteMultipartUpload>",+ ...sortedParts.map((p) => ` <Part><PartNumber>${p.partNumber}</PartNumber><ETag>"${p.etag}"</ETag></Part>`),+ "</CompleteMultipartUpload>"+ ].join("\n");++ const signedHeaders = signS3Request(this.config, {+ method: "POST",+ url: url.toString(),+ headers: { "content-type": "application/xml" },+ body: xmlPayload+ });++ return withRetry(async () => {+ const response = await fetch(url.toString(), {+ method: "POST",+ headers: signedHeaders,+ body: xmlPayload+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ return {+ id: `s3_${this.config.bucket}_${key}`,+ path: key,+ name: key.split("/").pop() || key,+ provider: "s3-compatible",+ providerId: key,+ updatedAt: new Date()+ };+ });+ }++ /**+ * S3 Multipart Upload: Abort and purge incomplete parts+ */+ public async abortMultipartUpload(key: string, uploadId: string): Promise<void> {+ const url = new URL(this.getObjectUrl(key));+ url.searchParams.set("uploadId", uploadId);++ const signedHeaders = signS3Request(this.config, {+ method: "DELETE",+ url: url.toString()+ });++ await withRetry(async () => {+ const response = await fetch(url.toString(), {+ method: "DELETE",+ headers: signedHeaders+ });++ if (!response.ok && response.status !== 404) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ /**+ * Generates a SigV4 Presigned Download or Upload URL.+ */+ public getPresignedUrl(key: string, options: PresignUrlOptions = {}): string {+ const url = this.getObjectUrl(key);+ return createPresignedS3Url(this.config, url, options);+ }++ private async handleErrorResponse(response: Response): Promise<StorageError> {+ let errorText = "";+ try {+ errorText = await response.text();+ } catch {+ errorText = response.statusText;+ }++ if (response.status === 404 || errorText.includes("NoSuchKey")) {+ return new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: `S3 Object not found (Status 404)`,+ provider: "s3-compatible",+ statusCode: 404,+ retryable: false+ });+ }++ if (response.status === 403 || errorText.includes("AccessDenied")) {+ return new StorageError({+ code: BYOCErrorCode.PERMISSION_DENIED,+ message: "S3 Access Denied: Invalid credentials or insufficient permissions.",+ provider: "s3-compatible",+ statusCode: 403,+ retryable: false+ });+ }++ return new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: `S3 Error (${response.status}): ${errorText}`,+ provider: "s3-compatible",+ statusCode: response.status,+ retryable: response.status >= 500+ });+ }+}++/**+ * Parses S3 ListObjectsV2 XML responses extracting files and virtual folder prefixes.+ */+export function parseS3ListXml(xml: string, bucket: string, rootPrefix: string = ""): StorageObject[] {+ const results: StorageObject[] = [];++ // Parse CommonPrefixes (Folders)+ const prefixMatches = xml.matchAll(/<CommonPrefixes>[\s\S]*?<Prefix>(.*?)<\/Prefix>[\s\S]*?<\/CommonPrefixes>/g);+ for (const match of prefixMatches) {+ if (match[1]) {+ const fullKey = match[1].replace(/\/+$/, "");+ const virtualPath = rootPrefix && fullKey.startsWith(rootPrefix + "/") ? fullKey.substring(rootPrefix.length + 1) : fullKey;+ const name = virtualPath.split("/").pop() || virtualPath;+ results.push({+ id: `s3_${bucket}_${fullKey}`,+ path: virtualPath,+ name,+ provider: "s3-compatible",+ providerId: fullKey,+ type: "folder"+ });+ }+ }++ // Parse Contents (Files)+ const contentMatches = xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g);+ for (const match of contentMatches) {+ const block = match[1] || "";+ const keyMatch = block.match(/<Key>(.*?)<\/Key>/);+ const sizeMatch = block.match(/<Size>(\d+)<\/Size>/);+ const etagMatch = block.match(/<ETag>(.*?)<\/ETag>/);+ const lastModMatch = block.match(/<LastModified>(.*?)<\/LastModified>/);++ if (keyMatch && keyMatch[1]) {+ const fullKey = keyMatch[1];+ // Skip directory marker keys (e.g. "folder/")+ if (fullKey.endsWith("/")) continue;++ const virtualPath = rootPrefix && fullKey.startsWith(rootPrefix + "/") ? fullKey.substring(rootPrefix.length + 1) : fullKey;+ const name = virtualPath.split("/").pop() || virtualPath;++ results.push({+ id: `s3_${bucket}_${fullKey}`,+ path: virtualPath,+ name,+ provider: "s3-compatible",+ providerId: fullKey,+ type: "file",+ size: sizeMatch && sizeMatch[1] ? Number(sizeMatch[1]) : undefined,+ checksum: etagMatch && etagMatch[1] ? etagMatch[1].replace(/"/g, "") : undefined,+ updatedAt: lastModMatch && lastModMatch[1] ? new Date(lastModMatch[1]) : undefined+ });+ }+ }++ return results;+}diff --git a/packages/s3-compatible/src/auth/signer.ts b/packages/s3-compatible/src/auth/signer.tsnew file mode 100644index 0000000..500f157--- /dev/null+++ b/packages/s3-compatible/src/auth/signer.ts@@ -0,0 +1,186 @@+import crypto from "node:crypto";++export interface SigV4Options {+ accessKeyId: string;+ secretAccessKey: string;+ region: string;+ service?: string;+}++export interface SignRequestParams {+ method: string;+ url: string;+ headers?: Record<string, string>;+ body?: Uint8Array | string;+ datetime?: Date;+}++export interface PresignUrlOptions {+ method?: string;+ expiresInSeconds?: number;+ datetime?: Date;+}++export function rfc3986UriEncode(str: string, encodeSlash: boolean = false): string {+ let result = encodeURIComponent(str).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);+ if (!encodeSlash) {+ result = result.replace(/%2F/g, "/");+ }+ return result;+}++function sha256Hex(data: string | NodeJS.ArrayBufferView): string {+ return crypto.createHash("sha256").update(data).digest("hex");+}++function hmacSha256(key: string | NodeJS.ArrayBufferView, data: string): Buffer {+ return crypto.createHmac("sha256", key).update(data).digest();+}++function getSignatureKey(key: string, dateStamp: string, regionName: string, serviceName: string): Buffer {+ const kDate = hmacSha256("AWS4" + key, dateStamp);+ const kRegion = hmacSha256(kDate, regionName);+ const kService = hmacSha256(kRegion, serviceName);+ const kSigning = hmacSha256(kService, "aws4_request");+ return kSigning;+}++/**+ * Builds standard RFC 3986 canonical query string sorted by encoded parameter key.+ */+export function buildCanonicalQueryString(url: URL): string {+ const params: Array<[string, string]> = [];+ url.searchParams.forEach((value, key) => {+ params.push([rfc3986UriEncode(key, true), rfc3986UriEncode(value, true)]);+ });++ // Sort by encoded key first, then encoded value+ params.sort(([k1, v1], [k2, v2]) => {+ if (k1 === k2) return v1.localeCompare(v2);+ return k1.localeCompare(k2);+ });++ return params.map(([k, v]) => `${k}=${v}`).join("&");+}++/**+ * Signs HTTP requests for S3 and S3-compatible endpoints using AWS Signature Version 4.+ */+export function signS3Request(+ options: SigV4Options,+ params: SignRequestParams+): Record<string, string> {+ const service = options.service || "s3";+ const now = params.datetime || new Date();+ const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");+ const dateStamp = amzDate.substring(0, 8);++ const parsedUrl = new URL(params.url);+ const host = parsedUrl.host;+ const canonicalUri = parsedUrl.pathname || "/";+ const canonicalQuery = buildCanonicalQueryString(parsedUrl);++ const bodyHash = params.body+ ? sha256Hex(params.body)+ : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";++ // Normalize all incoming headers to lowercase keys and trimmed values+ const normalizedHeaders: Record<string, string> = {+ host,+ "x-amz-date": amzDate,+ "x-amz-content-sha256": bodyHash+ };++ if (params.headers) {+ for (const [key, val] of Object.entries(params.headers)) {+ if (val !== undefined && val !== null) {+ normalizedHeaders[key.toLowerCase().trim()] = val.trim().replace(/\s+/g, " ");+ }+ }+ }++ const sortedHeaderKeys = Object.keys(normalizedHeaders).sort();+ const canonicalHeaders = sortedHeaderKeys.map((k) => `${k}:${normalizedHeaders[k]}\n`).join("");+ const signedHeaders = sortedHeaderKeys.join(";");++ const canonicalRequest = [+ params.method.toUpperCase(),+ canonicalUri,+ canonicalQuery,+ canonicalHeaders,+ signedHeaders,+ bodyHash+ ].join("\n");++ const credentialScope = `${dateStamp}/${options.region}/${service}/aws4_request`;+ const stringToSign = [+ "AWS4-HMAC-SHA256",+ amzDate,+ credentialScope,+ sha256Hex(canonicalRequest)+ ].join("\n");++ const signingKey = getSignatureKey(options.secretAccessKey, dateStamp, options.region, service);+ const signature = crypto.createHmac("sha256", signingKey).update(stringToSign).digest("hex");++ const authorizationHeader = `AWS4-HMAC-SHA256 Credential=${options.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;++ return {+ ...normalizedHeaders,+ Authorization: authorizationHeader+ };+}++/**+ * Creates an AWS SigV4 Presigned URL (query authenticated) for GET/PUT operations.+ */+export function createPresignedS3Url(+ options: SigV4Options,+ urlStr: string,+ presignOptions: PresignUrlOptions = {}+): string {+ const service = options.service || "s3";+ const now = presignOptions.datetime || new Date();+ const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");+ const dateStamp = amzDate.substring(0, 8);+ const expiresIn = presignOptions.expiresInSeconds || 3600;+ const method = (presignOptions.method || "GET").toUpperCase();++ const parsedUrl = new URL(urlStr);+ const host = parsedUrl.host;+ const canonicalUri = parsedUrl.pathname || "/";+ const credentialScope = `${dateStamp}/${options.region}/${service}/aws4_request`;++ parsedUrl.searchParams.set("X-Amz-Algorithm", "AWS4-HMAC-SHA256");+ parsedUrl.searchParams.set("X-Amz-Credential", `${options.accessKeyId}/${credentialScope}`);+ parsedUrl.searchParams.set("X-Amz-Date", amzDate);+ parsedUrl.searchParams.set("X-Amz-Expires", String(expiresIn));+ parsedUrl.searchParams.set("X-Amz-SignedHeaders", "host");++ const canonicalQuery = buildCanonicalQueryString(parsedUrl);+ const canonicalHeaders = `host:${host}\n`;+ const signedHeaders = "host";+ const bodyHash = "UNSIGNED-PAYLOAD";++ const canonicalRequest = [+ method,+ canonicalUri,+ canonicalQuery,+ canonicalHeaders,+ signedHeaders,+ bodyHash+ ].join("\n");++ const stringToSign = [+ "AWS4-HMAC-SHA256",+ amzDate,+ credentialScope,+ sha256Hex(canonicalRequest)+ ].join("\n");++ const signingKey = getSignatureKey(options.secretAccessKey, dateStamp, options.region, service);+ const signature = crypto.createHmac("sha256", signingKey).update(stringToSign).digest("hex");++ parsedUrl.searchParams.set("X-Amz-Signature", signature);+ return parsedUrl.toString();+}diff --git a/packages/s3-compatible/src/index.ts b/packages/s3-compatible/src/index.tsnew file mode 100644index 0000000..76e76a0--- /dev/null+++ b/packages/s3-compatible/src/index.ts@@ -0,0 +1,11 @@+export { S3CompatibleProvider, type S3ProviderConfig } from "./adapter.js";+export { S3HttpClient, parseS3ListXml, type S3ClientConfig, type S3UploadPart } from "./api/client.js";+export {+ signS3Request,+ createPresignedS3Url,+ buildCanonicalQueryString,+ rfc3986UriEncode,+ type SigV4Options,+ type SignRequestParams,+ type PresignUrlOptions+} from "./auth/signer.js";diff --git a/packages/s3-compatible/tests/adapter.test.ts b/packages/s3-compatible/tests/adapter.test.tsnew file mode 100644index 0000000..1963ed7--- /dev/null+++ b/packages/s3-compatible/tests/adapter.test.ts@@ -0,0 +1,208 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { S3CompatibleProvider } from "../src/adapter.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("S3CompatibleProvider", () => {+ const originalFetch = global.fetch;++ beforeEach(() => {+ global.fetch = vi.fn();+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ const validConfig = {+ endpoint: "https://my-account-id.r2.cloudflarestorage.com",+ bucket: "user-assets",+ region: "auto",+ accessKeyId: "mock-access-key",+ secretAccessKey: "mock-secret-key",+ rootPrefix: "production/data"+ };++ it("instantiates correctly and declares developer-cloud category", () => {+ const provider = new S3CompatibleProvider(validConfig);+ const manifest = provider.manifest();++ expect(manifest.id).toBe("s3-compatible");+ expect(manifest.category).toBe("developer-cloud");+ expect(manifest.authentication).toBe("access-key");+ expect(provider.capabilities().publicUrls).toBe(true);+ });++ it("throws INVALID_INPUT on missing required credentials", () => {+ expect(() => new S3CompatibleProvider({} as any)).toThrowError(StorageError);+ });++ it("signs and sends PUT Object request for upload with auto-path-style for R2", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ headers: new Headers({ etag: '"mock-md5-checksum"' })+ });++ const result = await provider.upload("users/123/avatar.png", "PNG Data", { mimeType: "image/png" });++ expect(result.id).toContain("s3_user-assets_production/data/users/123/avatar.png");+ expect(result.path).toBe("users/123/avatar.png"); // Assert virtual path encapsulation (no physical prefix leak)+ expect(result.checksum).toBe("mock-md5-checksum");++ // Path-style addressing includes /user-assets/ in URL+ expect(global.fetch).toHaveBeenCalledWith(+ "https://my-account-id.r2.cloudflarestorage.com/user-assets/production/data/users/123/avatar.png",+ expect.objectContaining({+ method: "PUT",+ headers: expect.objectContaining({+ Authorization: expect.stringContaining("AWS4-HMAC-SHA256")+ })+ })+ );+ });++ it("handles AWS S3 standard endpoint path-style addressing when bucket is not in hostname", () => {+ const awsProvider = new S3CompatibleProvider({+ endpoint: "https://s3.us-east-1.amazonaws.com",+ bucket: "my-corporate-bucket",+ region: "us-east-1",+ accessKeyId: "key",+ secretAccessKey: "secret"+ });++ const url = awsProvider.http.getObjectUrl("reports/2026#1?data.pdf");+ expect(url).toBe("https://s3.us-east-1.amazonaws.com/my-corporate-bucket/reports/2026%231%3Fdata.pdf");+ });++ it("downloads object and returns text", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200,+ headers: new Headers({ "content-type": "text/plain", "content-length": "12" }),+ text: async () => "Hello S3/R2!",+ arrayBuffer: async () => new TextEncoder().encode("Hello S3/R2!").buffer+ });++ const output = await provider.download("notes.txt");+ const text = await output.text();+ expect(text).toBe("Hello S3/R2!");+ });++ it("executes instant server-side copy using x-amz-copy-source", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 200+ });++ await provider.copy("docs/source.pdf", "docs/backup.pdf");++ expect(global.fetch).toHaveBeenCalledWith(+ "https://my-account-id.r2.cloudflarestorage.com/user-assets/production/data/docs/backup.pdf",+ expect.objectContaining({+ method: "PUT",+ headers: expect.objectContaining({+ "x-amz-copy-source": "/user-assets/production/data/docs/source.pdf"+ })+ })+ );+ });++ it("executes server-side move (copy + delete)", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ (global.fetch as any)+ .mockResolvedValueOnce({ ok: true, status: 200 }) // copy+ .mockResolvedValueOnce({ ok: true, status: 204 }); // delete++ await provider.move("docs/old.pdf", "docs/new.pdf");++ expect(global.fetch).toHaveBeenCalledTimes(2);+ });++ it("generates SigV4 presigned download URLs", () => {+ const provider = new S3CompatibleProvider(validConfig);+ const presignedUrl = provider.getSignedUrl("reports/annual.pdf", { expiresInSeconds: 1800 });++ expect(presignedUrl).toContain("X-Amz-Algorithm=AWS4-HMAC-SHA256");+ expect(presignedUrl).toContain("X-Amz-Expires=1800");+ expect(presignedUrl).toContain("X-Amz-Signature=");+ });++ it("maps 404 response to OBJECT_NOT_FOUND", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ (global.fetch as any).mockResolvedValueOnce({+ ok: false,+ status: 404,+ text: async () => "<Error><Code>NoSuchKey</Code></Error>"+ });++ await expect(provider.download("missing.txt")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.OBJECT_NOT_FOUND+ })+ );+ });++ it("lists files and folder prefixes using ListObjectsV2 with pagination", async () => {+ const provider = new S3CompatibleProvider(validConfig);++ const mockXmlPage1 = `<?xml version="1.0" encoding="UTF-8"?>+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">+ <Name>user-assets</Name>+ <Prefix>production/data/</Prefix>+ <IsTruncated>true</IsTruncated>+ <NextContinuationToken>token-page-2</NextContinuationToken>+ <Contents>+ <Key>production/data/document1.pdf</Key>+ <Size>4096</Size>+ </Contents>+</ListBucketResult>`;++ const mockXmlPage2 = `<?xml version="1.0" encoding="UTF-8"?>+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">+ <Name>user-assets</Name>+ <Prefix>production/data/</Prefix>+ <IsTruncated>false</IsTruncated>+ <Contents>+ <Key>production/data/document2.pdf</Key>+ <Size>8192</Size>+ </Contents>+ <CommonPrefixes>+ <Prefix>production/data/photos/</Prefix>+ </CommonPrefixes>+</ListBucketResult>`;++ (global.fetch as any)+ .mockResolvedValueOnce({+ ok: true,+ status: 200,+ text: async () => mockXmlPage1+ })+ .mockResolvedValueOnce({+ ok: true,+ status: 200,+ text: async () => mockXmlPage2+ });++ const items = await provider.list();+ expect(items.length).toBe(3); // 2 files + 1 folder across 2 paginated requests++ const folder = items.find((i) => i.type === "folder");+ const file1 = items.find((i) => i.name === "document1.pdf");+ const file2 = items.find((i) => i.name === "document2.pdf");++ expect(folder?.name).toBe("photos");+ expect(folder?.path).toBe("photos"); // virtual path+ expect(file1?.path).toBe("document1.pdf"); // virtual path+ expect(file2?.path).toBe("document2.pdf"); // virtual path+ expect(file2?.size).toBe(8192);+ });+});diff --git a/packages/s3-compatible/tests/auth/signer.test.ts b/packages/s3-compatible/tests/auth/signer.test.tsnew file mode 100644index 0000000..866cd65--- /dev/null+++ b/packages/s3-compatible/tests/auth/signer.test.ts@@ -0,0 +1,100 @@+import { describe, it, expect } from "vitest";+import { signS3Request, buildCanonicalQueryString, createPresignedS3Url } from "../../src/auth/signer.js";++describe("AWS SigV4 Signer & Canonicalization", () => {+ const options = {+ accessKeyId: "AKIAIOSFODNN7EXAMPLE",+ secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",+ region: "us-east-1",+ service: "s3"+ };++ const fixedDate = new Date("2026-08-25T00:00:00.000Z");++ it("matches the exact signature for AWS SigV4 reference vectors", () => {+ // Official AWS Reference Parameters+ const awsOptions = {+ accessKeyId: "AKIDEXAMPLE",+ secretAccessKey: "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",+ region: "us-east-1",+ service: "s3"+ };++ const awsDate = new Date("2013-05-24T00:00:00.000Z");+ const signed = signS3Request(awsOptions, {+ method: "GET",+ url: "https://example.amazonaws.com/test.txt",+ headers: {+ "x-amz-storage-class": "REDUCED_REDUNDANCY"+ },+ datetime: awsDate+ });++ expect(signed["x-amz-date"]).toBe("20130524T000000Z");+ expect(signed["x-amz-content-sha256"]).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");+ expect(signed.Authorization).toBe(+ "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-storage-class, Signature=c29c0c4b3f775eacb23837eb912405953619018f2417926a9ed48e32352e0e3b"+ );+ });++ it("produces identical signatures regardless of header casing (Bug #3 fix)", () => {+ const url = "https://examplebucket.s3.amazonaws.com/test.txt";++ const signedWithUpper = signS3Request(options, {+ method: "PUT",+ url,+ headers: { "Content-Type": "application/json", "X-Amz-Meta-Author": "Alice" },+ body: '{"status":"ok"}',+ datetime: fixedDate+ });++ const signedWithLower = signS3Request(options, {+ method: "PUT",+ url,+ headers: { "content-type": "application/json", "x-amz-meta-author": "Alice" },+ body: '{"status":"ok"}',+ datetime: fixedDate+ });++ expect(signedWithUpper.Authorization).toBe(signedWithLower.Authorization);+ expect(signedWithUpper.Authorization).toContain("content-type;host;x-amz-content-sha256;x-amz-date;x-amz-meta-author");+ });++ it("correctly encodes and sorts multi-parameter query strings with %20 (Bug #4 fix)", () => {+ const url = new URL("https://examplebucket.s3.amazonaws.com/?prefix=my+folder&list-type=2&delimiter=%2F");+ const canonicalQuery = buildCanonicalQueryString(url);++ // Must be sorted alphabetically by key: delimiter -> list-type -> prefix+ // And spaces encoded as %20+ expect(canonicalQuery).toBe("delimiter=%2F&list-type=2&prefix=my%20folder");+ });++ it("handles complex S3 ListObjectsV2 query signing", () => {+ const url = "https://my-bucket.s3.us-east-1.amazonaws.com/?list-type=2&prefix=photos%2F2026%2F&delimiter=%2F&max-keys=100";++ const signed = signS3Request(options, {+ method: "GET",+ url,+ datetime: fixedDate+ });++ expect(signed.Authorization).toMatch(/^AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE\/20260825\/us-east-1\/s3\/aws4_request/);+ expect(signed.Authorization).toContain("Signature=");+ });++ it("generates valid presigned URL query parameters with AWS4-HMAC-SHA256", () => {+ const url = "https://examplebucket.s3.us-east-1.amazonaws.com/report.pdf";+ const presigned = createPresignedS3Url(options, url, {+ expiresInSeconds: 3600,+ datetime: fixedDate+ });++ const parsed = new URL(presigned);+ expect(parsed.searchParams.get("X-Amz-Algorithm")).toBe("AWS4-HMAC-SHA256");+ expect(parsed.searchParams.get("X-Amz-Credential")).toBe("AKIAIOSFODNN7EXAMPLE/20260825/us-east-1/s3/aws4_request");+ expect(parsed.searchParams.get("X-Amz-Date")).toBe("20260825T000000Z");+ expect(parsed.searchParams.get("X-Amz-Expires")).toBe("3600");+ expect(parsed.searchParams.get("X-Amz-SignedHeaders")).toBe("host");+ expect(parsed.searchParams.get("X-Amz-Signature")).toBeTruthy();+ });+});diff --git a/packages/s3-compatible/tsconfig.json b/packages/s3-compatible/tsconfig.jsonnew file mode 100644index 0000000..134f8ff--- /dev/null+++ b/packages/s3-compatible/tsconfig.json@@ -0,0 +1,13 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": "src",+ "outDir": "dist",+ "composite": true,+ "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"+ },+ "references": [+ { "path": "../core" }+ ],+ "include": ["src/**/*"]+}diff --git a/packages/webdav/LICENSE b/packages/webdav/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/packages/webdav/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/packages/webdav/README.md b/packages/webdav/README.mdnew file mode 100644index 0000000..8fcad97--- /dev/null+++ b/packages/webdav/README.md@@ -0,0 +1,51 @@+# @byoc/webdav++WebDAV provider adapter for **BYOC (Bring Your Own Cloud)**: Nextcloud, ownCloud, Synology NAS, and any RFC 4918 WebDAV server.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Requires `@byoc/core`.+>+> **Status: v0.2.0.** Unit tested, and validated against a live RFC 4918 server in CI.++## Install++```bash+npm install @byoc/core @byoc/webdav+```++## Usage++```ts+import { BYOC } from "@byoc/core";+import { WebDAVProvider } from "@byoc/webdav";++const storage = new BYOC({+ provider: new WebDAVProvider({+ endpoint: "https://nextcloud.company.com/remote.php/dav/files/alex/",+ username: "alex",+ password: process.env.NEXTCLOUD_APP_PASSWORD!,+ rootFolder: "MyApplication"+ })+});++await storage.connect();+await storage.writeText("notes/todo.md", "# This week");+```++Bearer-token servers can pass `token` instead of `username`/`password`.++> Use an **app password**, not the account password. Nextcloud and Synology both issue scoped app passwords that can be revoked independently.++## What this adapter handles++- **PROPFIND listing**: multistatus XML parsed into `StorageObject[]`, with `Depth: 1` for single-level directory listings.+- **Folder hierarchy**: `MKCOL` issued for each missing ancestor before an upload.+- **Path encoding**: segments percent-encoded per RFC 3986, so `#`, `?`, spaces, and unicode filenames survive.+- **Quota**: reported via `quota-available-bytes` where the server supports it.++## Capabilities++WebDAV has no resumable-upload protocol, so `resumableUploads` is `false`. Large files are sent as a single `PUT`.++## License++[Apache-2.0](./LICENSE)diff --git a/packages/webdav/package.json b/packages/webdav/package.jsonnew file mode 100644index 0000000..2b22a6b--- /dev/null+++ b/packages/webdav/package.json@@ -0,0 +1,55 @@+{+ "name": "@byoc/webdav",+ "version": "0.2.1",+ "description": "Universal WebDAV storage adapter for Nextcloud, ownCloud, and Synology NAS",+ "type": "module",+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js",+ "default": "./dist/index.js"+ }+ },+ "files": [+ "dist",+ "!dist/tsconfig.tsbuildinfo",+ "README.md",+ "LICENSE"+ ],+ "scripts": {+ "build": "tsc -b",+ "clean": "rm -rf dist tsconfig.tsbuildinfo"+ },+ "dependencies": {+ "@byoc/core": "^0.2.1"+ },+ "keywords": [+ "byoc",+ "webdav",+ "nextcloud",+ "owncloud",+ "synology",+ "self-hosted",+ "nas"+ ],+ "author": "Ajay Ramineni",+ "license": "Apache-2.0",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Ajayvarmaramineni/BYOC.git",+ "directory": "packages/webdav"+ },+ "publishConfig": {+ "access": "public"+ },+ "homepage": "https://github.com/Ajayvarmaramineni/BYOC/tree/main/packages/webdav#readme",+ "bugs": {+ "url": "https://github.com/Ajayvarmaramineni/BYOC/issues"+ },+ "engines": {+ "node": ">=20"+ },+ "sideEffects": false+}diff --git a/packages/webdav/src/adapter.ts b/packages/webdav/src/adapter.tsnew file mode 100644index 0000000..d2f98e3--- /dev/null+++ b/packages/webdav/src/adapter.ts@@ -0,0 +1,235 @@+import type {+ BYOCProvider,+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ UploadOptions,+ BackupOptions,+ StorageQuota+} from "@byoc/core";+import {+ BYOCErrorCode,+ StorageError,+ normalizeVirtualPath,+ getBasename,+ getDirname+} from "@byoc/core";+import { WebDAVHttpClient, type WebDAVClientConfig } from "./api/client.js";++export interface WebDAVProviderConfig extends WebDAVClientConfig {+ rootFolder?: string;+}++/**+ * WebDAVProvider — Self-hosted storage adapter for Nextcloud, ownCloud, and Synology NAS.+ */+export class WebDAVProvider implements BYOCProvider {+ public readonly http: WebDAVHttpClient;+ public readonly rootFolder: string;++ constructor(public readonly config: WebDAVProviderConfig) {+ if (!config || !config.endpoint) {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "WebDAVProvider requires an 'endpoint' URL.",+ provider: "webdav",+ retryable: false+ });+ }++ this.rootFolder = config.rootFolder ? normalizeVirtualPath(config.rootFolder) : "BYOC";+ this.http = new WebDAVHttpClient(config);+ }++ public manifest(): ProviderManifest {+ return {+ id: "webdav",+ name: "Nextcloud / WebDAV",+ category: "self-hosted",+ authentication: this.config.token ? "oauth2" : "basic",+ supportsUserOwnedStorage: true,+ adapterVersion: "0.2.0"+ };+ }++ public capabilities(): ProviderCapabilities {+ return {+ folders: true,+ sharing: false,+ publicUrls: false,+ resumableUploads: false,+ versioning: false,+ quota: true,+ serverSideCopy: true+ };+ }++ public async connect(): Promise<void> {+ // Validate connection / auth credentials and ensure root app folder exists on Nextcloud / WebDAV+ if (this.rootFolder) {+ try {+ await this.http.mkcol(this.rootFolder);+ } catch (err) {+ // 405 (Folder already exists) or 301 is acceptable; authentication/network errors must be thrown+ if (StorageError.isStorageError(err) && (err.statusCode === 405 || err.statusCode === 301)) {+ return;+ }+ throw err;+ }+ } else {+ // If no root folder, verify connection with lightweight PROPFIND Depth 0+ await this.http.propfind("", 0);+ }+ }++ public async disconnect(): Promise<void> {+ // Stateless+ }++ public async upload(+ path: string,+ data: StorageInput,+ options?: UploadOptions+ ): Promise<StorageObject> {+ const fullPath = this.toFullPath(path);+ const dirname = getDirname(fullPath);++ if (dirname) {+ await this.ensureFolderHierarchy(dirname);+ }++ const result = await this.http.put(fullPath, data, options?.mimeType, options?.onProgress);+ return {+ ...result,+ path: normalizeVirtualPath(path)+ };+ }++ public async download(path: string): Promise<StorageOutput> {+ const fullPath = this.toFullPath(path);+ const res = await this.http.get(fullPath);++ return {+ stream: res.body as any,+ arrayBuffer: () => res.arrayBuffer(),+ text: () => res.text(),+ metadata: {+ id: `webdav_${fullPath}`,+ path: normalizeVirtualPath(path),+ name: getBasename(fullPath),+ provider: "webdav",+ providerId: fullPath,+ size: Number(res.headers.get("content-length")) || undefined,+ mimeType: res.headers.get("content-type") || "application/octet-stream",+ checksum: res.headers.get("etag")?.replace(/"/g, "")+ }+ };+ }++ public async delete(path: string): Promise<void> {+ const fullPath = this.toFullPath(path);+ await this.http.delete(fullPath);+ }++ public async list(path?: string): Promise<StorageObject[]> {+ const fullPath = path ? this.toFullPath(path) : this.rootFolder;+ return this.http.propfind(fullPath, 1, this.rootFolder);+ }++ public async exists(path: string): Promise<boolean> {+ const fullPath = this.toFullPath(path);+ try {+ await this.http.head(fullPath);+ return true;+ } catch (err) {+ if (StorageError.isStorageError(err) && err.code === BYOCErrorCode.OBJECT_NOT_FOUND) {+ return false;+ }+ throw err;+ }+ }++ public async metadata(path: string): Promise<StorageObject> {+ const fullPath = this.toFullPath(path);+ const result = await this.http.head(fullPath);+ return {+ ...result,+ path: normalizeVirtualPath(path)+ };+ }++ public async createFolder(path: string): Promise<StorageObject> {+ const fullPath = this.toFullPath(path);+ await this.ensureFolderHierarchy(fullPath);+ return {+ id: `webdav_${fullPath}`,+ path: normalizeVirtualPath(path),+ name: getBasename(fullPath),+ provider: "webdav",+ providerId: fullPath,+ type: "folder"+ };+ }++ /**+ * RFC 2518: Server-side file/folder copy+ */+ public async copy(source: string, destination: string): Promise<void> {+ const src = this.toFullPath(source);+ const dest = this.toFullPath(destination);+ const dirname = getDirname(dest);+ if (dirname) {+ await this.ensureFolderHierarchy(dirname);+ }+ await this.http.copy(src, dest);+ }++ /**+ * RFC 2518: Server-side file/folder move+ */+ public async move(source: string, destination: string): Promise<void> {+ const src = this.toFullPath(source);+ const dest = this.toFullPath(destination);+ const dirname = getDirname(dest);+ if (dirname) {+ await this.ensureFolderHierarchy(dirname);+ }+ await this.http.move(src, dest);+ }++ /**+ * RFC 4331: Query user quota+ */+ public async quota(): Promise<StorageQuota> {+ return this.http.getQuota(this.rootFolder);+ }++ public async backup(payload: StorageInput, options?: BackupOptions): Promise<StorageObject> {+ const folder = normalizeVirtualPath(options?.folder ?? "Backups");+ const filename = options?.filename ?? `backup-${new Date().toISOString().replace(/[:.]/g, "-")}.json`;+ const targetPath = folder ? `${folder}/${filename}` : filename;++ return this.upload(targetPath, payload, {+ mimeType: options?.mimeType ?? "application/json",+ onProgress: options?.onProgress+ });+ }++ private toFullPath(path: string): string {+ const normalized = normalizeVirtualPath(path);+ if (!this.rootFolder) return normalized;+ return `${this.rootFolder}/${normalized}`;+ }++ private async ensureFolderHierarchy(folderPath: string): Promise<void> {+ const segments = folderPath.split("/").filter(Boolean);+ let current = "";++ for (const segment of segments) {+ current = current ? `${current}/${segment}` : segment;+ await this.http.mkcol(current);+ }+ }+}diff --git a/packages/webdav/src/api/client.ts b/packages/webdav/src/api/client.tsnew file mode 100644index 0000000..260a652--- /dev/null+++ b/packages/webdav/src/api/client.ts@@ -0,0 +1,437 @@+import {+ withRetry,+ StorageError,+ BYOCErrorCode,+ encodePathSegments,+ type StorageObject,+ type StorageInput,+ type StorageQuota,+ type UploadProgress+} from "@byoc/core";+import { Readable } from "node:stream";++export interface WebDAVClientConfig {+ endpoint: string;+ username?: string;+ password?: string;+ token?: string;+}++export class WebDAVHttpClient {+ private readonly baseUrl: string;++ constructor(public readonly config: WebDAVClientConfig) {+ this.baseUrl = config.endpoint.replace(/\/+$/, "");+ }++ private getAuthHeader(): string | undefined {+ if (this.config.token) {+ return `Bearer ${this.config.token}`;+ }+ if (this.config.username && this.config.password) {+ const creds = `${this.config.username}:${this.config.password}`;+ return `Basic ${Buffer.from(creds).toString("base64")}`;+ }+ return undefined;+ }++ public getFullUrl(path: string): string {+ const encoded = encodePathSegments(path);+ return `${this.baseUrl}/${encoded}`;+ }++ public async put(+ path: string,+ data: StorageInput,+ mimeType?: string,+ onProgress?: (progress: UploadProgress) => void+ ): Promise<StorageObject> {+ const url = this.getFullUrl(path);+ let bodyPayload: any;+ let payloadSize: number | undefined;++ if (typeof data === "string") {+ const bytes = new TextEncoder().encode(data);+ bodyPayload = bytes;+ payloadSize = bytes.byteLength;+ } else if (data instanceof Uint8Array) {+ bodyPayload = data;+ payloadSize = data.byteLength;+ } else if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {+ bodyPayload = data;+ payloadSize = data.byteLength;+ } else if (data instanceof ArrayBuffer) {+ bodyPayload = new Uint8Array(data);+ payloadSize = data.byteLength;+ } else if (typeof Blob !== "undefined" && data instanceof Blob) {+ bodyPayload = data;+ payloadSize = data.size;+ } else if (+ (typeof ReadableStream !== "undefined" && data instanceof ReadableStream) ||+ (typeof Readable !== "undefined" && data instanceof Readable)+ ) {+ bodyPayload = data;+ } else {+ throw new StorageError({+ code: BYOCErrorCode.INVALID_INPUT,+ message: "Unsupported data payload type for WebDAV upload.",+ provider: "webdav"+ });+ }++ const headers: Record<string, string> = {+ "Content-Type": mimeType || "application/octet-stream"+ };++ if (payloadSize !== undefined) {+ headers["Content-Length"] = String(payloadSize);+ }++ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "PUT",+ headers,+ body: bodyPayload,+ // @ts-ignore Node fetch streaming support+ duplex: "half"+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ if (onProgress && payloadSize !== undefined) {+ onProgress({+ bytesUploaded: payloadSize,+ totalBytes: payloadSize,+ percentage: 100+ });+ }++ const etag = response.headers.get("etag")?.replace(/"/g, "");++ return {+ id: `webdav_${path}`,+ path,+ name: path.split("/").pop() || path,+ provider: "webdav",+ providerId: path,+ size: payloadSize,+ mimeType: mimeType || "application/octet-stream",+ checksum: etag,+ updatedAt: new Date()+ };+ });+ }++ public async get(path: string): Promise<Response> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {};+ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "GET",+ headers+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ return response;+ });+ }++ public async delete(path: string): Promise<void> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {};+ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ await withRetry(async () => {+ const response = await fetch(url, {+ method: "DELETE",+ headers+ });++ if (!response.ok && response.status !== 404 && response.status !== 204) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ public async mkcol(path: string): Promise<void> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {};+ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ await withRetry(async () => {+ const response = await fetch(url, {+ method: "MKCOL",+ headers+ });++ // 201 Created or 405 (Folder already exists) are successful+ if (!response.ok && response.status !== 405 && response.status !== 301) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ public async head(path: string): Promise<StorageObject> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {};+ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "HEAD",+ headers+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const contentType = response.headers.get("content-type") || "application/octet-stream";+ const contentLength = response.headers.get("content-length");+ const etag = response.headers.get("etag")?.replace(/"/g, "");+ const lastModified = response.headers.get("last-modified");++ return {+ id: `webdav_${path}`,+ path,+ name: path.split("/").pop() || path,+ provider: "webdav",+ providerId: path,+ size: contentLength ? Number(contentLength) : undefined,+ mimeType: contentType,+ checksum: etag,+ updatedAt: lastModified ? new Date(lastModified) : undefined+ };+ });+ }++ public async copy(sourcePath: string, destPath: string, overwrite: boolean = true): Promise<void> {+ const sourceUrl = this.getFullUrl(sourcePath);+ const destUrl = this.getFullUrl(destPath);+ const headers: Record<string, string> = {+ Destination: destUrl,+ Overwrite: overwrite ? "T" : "F"+ };++ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ await withRetry(async () => {+ const response = await fetch(sourceUrl, {+ method: "COPY",+ headers+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ public async move(sourcePath: string, destPath: string, overwrite: boolean = true): Promise<void> {+ const sourceUrl = this.getFullUrl(sourcePath);+ const destUrl = this.getFullUrl(destPath);+ const headers: Record<string, string> = {+ Destination: destUrl,+ Overwrite: overwrite ? "T" : "F"+ };++ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ await withRetry(async () => {+ const response = await fetch(sourceUrl, {+ method: "MOVE",+ headers+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }+ });+ }++ public async propfind(path: string, depth: number = 1, rootFolder: string = ""): Promise<StorageObject[]> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {+ Depth: String(depth),+ "Content-Type": "application/xml; charset=utf-8"+ };++ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "PROPFIND",+ headers+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const xmlText = await response.text();+ return parseWebDavPropfindXml(xmlText, path, rootFolder);+ });+ }++ /**+ * RFC 4331: Query storage quota via PROPFIND Depth: 0+ */+ public async getQuota(path: string = ""): Promise<StorageQuota> {+ const url = this.getFullUrl(path);+ const headers: Record<string, string> = {+ Depth: "0",+ "Content-Type": "application/xml; charset=utf-8"+ };++ const auth = this.getAuthHeader();+ if (auth) headers["Authorization"] = auth;++ const queryBody = `<?xml version="1.0" encoding="utf-8" ?>+<d:propfind xmlns:d="DAV:">+ <d:prop>+ <d:quota-available-bytes/>+ <d:quota-used-bytes/>+ </d:prop>+</d:propfind>`;++ return withRetry(async () => {+ const response = await fetch(url, {+ method: "PROPFIND",+ headers,+ body: queryBody+ });++ if (!response.ok) {+ throw await this.handleErrorResponse(response);+ }++ const xml = await response.text();+ const availMatch = xml.match(/<[a-zA-Z0-9:]*quota-available-bytes>(\d+)<\/[a-zA-Z0-9:]*quota-available-bytes>/i);+ const usedMatch = xml.match(/<[a-zA-Z0-9:]*quota-used-bytes>(\d+)<\/[a-zA-Z0-9:]*quota-used-bytes>/i);++ const available = availMatch && availMatch[1] ? Number(availMatch[1]) : undefined;+ const used = usedMatch && usedMatch[1] ? Number(usedMatch[1]) : 0;+ const total = available !== undefined ? used + available : undefined;++ return {+ used,+ total,+ available+ };+ });+ }++ private async handleErrorResponse(response: Response): Promise<StorageError> {+ const errorText = await response.text().catch(() => response.statusText);++ if (response.status === 404) {+ return new StorageError({+ code: BYOCErrorCode.OBJECT_NOT_FOUND,+ message: "WebDAV object not found (404).",+ provider: "webdav",+ statusCode: 404,+ retryable: false+ });+ }++ if (response.status === 401 || response.status === 403) {+ return new StorageError({+ code: BYOCErrorCode.PERMISSION_DENIED,+ message: "WebDAV authentication failed: Invalid credentials or permission denied.",+ provider: "webdav",+ statusCode: response.status,+ retryable: false+ });+ }++ if (response.status === 507) {+ return new StorageError({+ code: BYOCErrorCode.QUOTA_EXCEEDED,+ message: "WebDAV insufficient storage / user quota exceeded (507).",+ provider: "webdav",+ statusCode: 507,+ retryable: false+ });+ }++ return new StorageError({+ code: BYOCErrorCode.PROVIDER_UNAVAILABLE,+ message: `WebDAV Server Error (${response.status}): ${errorText}`,+ provider: "webdav",+ statusCode: response.status,+ retryable: response.status >= 500+ });+ }+}++/**+ * Parses WebDAV PROPFIND Multistatus XML responses extracting child files and folders.+ */+export function parseWebDavPropfindXml(xml: string, targetPath: string, rootFolder: string = ""): StorageObject[] {+ const results: StorageObject[] = [];+ const cleanTarget = targetPath.replace(/^\/+|\/+$/g, "");++ const responseMatches = xml.matchAll(/<[a-zA-Z0-9:]*response>([\s\S]*?)<\/[a-zA-Z0-9:]*response>/g);++ for (const match of responseMatches) {+ const block = match[1] || "";+ const hrefMatch = block.match(/<[a-zA-Z0-9:]*href>(.*?)<\/[a-zA-Z0-9:]*href>/);+ if (!hrefMatch || !hrefMatch[1]) continue;++ const rawHref = decodeURI(hrefMatch[1]);+ const normalizedHref = rawHref.replace(/\/+$/, "");+ const segments = normalizedHref.split("/").filter(Boolean);+ const itemName = segments[segments.length - 1] || "";++ // Skip the parent directory self-reference+ if (!itemName || normalizedHref.endsWith(cleanTarget)) {+ continue;+ }++ const isFolder = /<[a-zA-Z0-9:]*collection\s*\/?>/i.test(block);+ const sizeMatch = block.match(/<[a-zA-Z0-9:]*getcontentlength>(\d+)<\/[a-zA-Z0-9:]*getcontentlength>/);+ const typeMatch = block.match(/<[a-zA-Z0-9:]*getcontenttype>(.*?)<\/[a-zA-Z0-9:]*getcontenttype>/);+ const etagMatch = block.match(/<[a-zA-Z0-9:]*getetag>(.*?)<\/[a-zA-Z0-9:]*getetag>/);+ const lastModMatch = block.match(/<[a-zA-Z0-9:]*getlastmodified>(.*?)<\/[a-zA-Z0-9:]*getlastmodified>/);++ const relativePath = cleanTarget ? `${cleanTarget}/${itemName}` : itemName;+ const cleanRoot = rootFolder.replace(/^\/+|\/+$/g, "");+ const virtualPath = cleanRoot && relativePath.startsWith(cleanRoot + "/")+ ? relativePath.substring(cleanRoot.length + 1)+ : cleanRoot && relativePath === cleanRoot+ ? ""+ : relativePath;++ results.push({+ id: `webdav_${relativePath}`,+ path: virtualPath,+ name: itemName,+ provider: "webdav",+ providerId: relativePath,+ type: isFolder ? "folder" : "file",+ size: sizeMatch && sizeMatch[1] ? Number(sizeMatch[1]) : undefined,+ mimeType: typeMatch && typeMatch[1] ? typeMatch[1].trim() : isFolder ? undefined : "application/octet-stream",+ checksum: etagMatch && etagMatch[1] ? etagMatch[1].replace(/"/g, "") : undefined,+ updatedAt: lastModMatch && lastModMatch[1] ? new Date(lastModMatch[1]) : undefined+ });+ }++ return results;+}diff --git a/packages/webdav/src/index.ts b/packages/webdav/src/index.tsnew file mode 100644index 0000000..277a61f--- /dev/null+++ b/packages/webdav/src/index.ts@@ -0,0 +1,2 @@+export { WebDAVProvider, type WebDAVProviderConfig } from "./adapter.js";+export { WebDAVHttpClient, parseWebDavPropfindXml, type WebDAVClientConfig } from "./api/client.js";diff --git a/packages/webdav/tests/adapter.test.ts b/packages/webdav/tests/adapter.test.tsnew file mode 100644index 0000000..4b0340c--- /dev/null+++ b/packages/webdav/tests/adapter.test.ts@@ -0,0 +1,216 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import { WebDAVProvider } from "../src/adapter.js";+import { BYOCErrorCode, StorageError } from "@byoc/core";++describe("WebDAVProvider", () => {+ const originalFetch = global.fetch;++ beforeEach(() => {+ global.fetch = vi.fn();+ });++ afterEach(() => {+ global.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ const validConfig = {+ endpoint: "https://nextcloud.mycompany.com/remote.php/dav/files/user/",+ username: "john_doe",+ password: "app-password-xyz",+ rootFolder: "MyApp"+ };++ it("declares self-hosted category and standard capabilities", () => {+ const provider = new WebDAVProvider(validConfig);+ const manifest = provider.manifest();++ expect(manifest.id).toBe("webdav");+ expect(manifest.category).toBe("self-hosted");+ expect(manifest.authentication).toBe("basic");+ expect(provider.capabilities().folders).toBe(true);+ expect(provider.capabilities().quota).toBe(true);+ expect(provider.capabilities().serverSideCopy).toBe(true);+ });++ it("throws INVALID_INPUT when endpoint is omitted", () => {+ expect(() => new WebDAVProvider({} as any)).toThrowError(StorageError);+ });++ it("uploads file to WebDAV server using HTTP PUT with Basic Auth", async () => {+ const provider = new WebDAVProvider(validConfig);++ // 1. MKCOL for root folder MyApp+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 2. MKCOL for parent folder MyApp/documents+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 3. PUT file+ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 201,+ headers: new Headers({ etag: '"etag-webdav-123"' })+ });++ const result = await provider.upload("documents/notes.txt", "WebDAV content");++ expect(result.id).toBe("webdav_MyApp/documents/notes.txt");+ expect(result.path).toBe("documents/notes.txt"); // Virtual path (does not leak MyApp/)+ expect(result.checksum).toBe("etag-webdav-123");++ expect(global.fetch).toHaveBeenCalledWith(+ "https://nextcloud.mycompany.com/remote.php/dav/files/user/MyApp/documents/notes.txt",+ expect.objectContaining({+ method: "PUT",+ headers: expect.objectContaining({+ Authorization: expect.stringContaining("Basic ")+ })+ })+ );+ });++ it("executes server-side COPY with Destination and Overwrite headers", async () => {+ const provider = new WebDAVProvider(validConfig);++ // 1. MKCOL for parent folder MyApp+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 2. MKCOL for parent folder MyApp/docs+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 3. COPY operation+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });++ await provider.copy("docs/source.pdf", "docs/copy.pdf");++ expect(global.fetch).toHaveBeenCalledWith(+ "https://nextcloud.mycompany.com/remote.php/dav/files/user/MyApp/docs/source.pdf",+ expect.objectContaining({+ method: "COPY",+ headers: expect.objectContaining({+ Destination: "https://nextcloud.mycompany.com/remote.php/dav/files/user/MyApp/docs/copy.pdf",+ Overwrite: "T"+ })+ })+ );+ });++ it("executes server-side MOVE with Destination header", async () => {+ const provider = new WebDAVProvider(validConfig);++ // 1. MKCOL for parent folder MyApp+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 2. MKCOL for parent folder MyApp/archive+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });+ // 3. MOVE operation+ (global.fetch as any).mockResolvedValueOnce({ ok: true, status: 201 });++ await provider.move("docs/old.pdf", "archive/new.pdf");++ expect(global.fetch).toHaveBeenCalledWith(+ "https://nextcloud.mycompany.com/remote.php/dav/files/user/MyApp/docs/old.pdf",+ expect.objectContaining({+ method: "MOVE",+ headers: expect.objectContaining({+ Destination: "https://nextcloud.mycompany.com/remote.php/dav/files/user/MyApp/archive/new.pdf"+ })+ })+ );+ });++ it("queries RFC 4331 storage quota via PROPFIND Depth: 0", async () => {+ const provider = new WebDAVProvider(validConfig);++ const mockQuotaXml = `<?xml version="1.0" encoding="utf-8" ?>+<d:multistatus xmlns:d="DAV:">+ <d:response>+ <d:href>/remote.php/dav/files/user/MyApp/</d:href>+ <d:propstat>+ <d:prop>+ <d:quota-available-bytes>53687091200</d:quota-available-bytes>+ <d:quota-used-bytes>10737418240</d:quota-used-bytes>+ </d:prop>+ </d:propstat>+ </d:response>+</d:multistatus>`;++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 207,+ text: async () => mockQuotaXml+ });++ const quota = await provider.quota();+ expect(quota.used).toBe(10737418240); // 10 GB+ expect(quota.available).toBe(53687091200); // 50 GB+ expect(quota.total).toBe(64424509440); // 60 GB+ });++ it("maps 404 to OBJECT_NOT_FOUND", async () => {+ const provider = new WebDAVProvider(validConfig);++ (global.fetch as any).mockResolvedValueOnce({+ ok: false,+ status: 404,+ text: async () => "File Not Found"+ });++ await expect(provider.download("missing.txt")).rejects.toThrowError(+ expect.objectContaining({+ code: BYOCErrorCode.OBJECT_NOT_FOUND+ })+ );+ });++ it("lists files and folders using PROPFIND XML", async () => {+ const provider = new WebDAVProvider(validConfig);++ const mockXml = `<?xml version="1.0" encoding="utf-8"?>+<d:multistatus xmlns:d="DAV:">+ <d:response>+ <d:href>/remote.php/dav/files/user/MyApp/</d:href>+ <d:propstat>+ <d:prop>+ <d:resourcetype><d:collection/></d:resourcetype>+ </d:prop>+ </d:propstat>+ </d:response>+ <d:response>+ <d:href>/remote.php/dav/files/user/MyApp/report.pdf</d:href>+ <d:propstat>+ <d:prop>+ <d:getcontentlength>8192</d:getcontentlength>+ <d:getcontenttype>application/pdf</d:getcontenttype>+ <d:getetag>"etag-report-456"</d:getetag>+ <d:resourcetype/>+ </d:prop>+ </d:propstat>+ </d:response>+ <d:response>+ <d:href>/remote.php/dav/files/user/MyApp/Archive/</d:href>+ <d:propstat>+ <d:prop>+ <d:resourcetype><d:collection/></d:resourcetype>+ </d:prop>+ </d:propstat>+ </d:response>+</d:multistatus>`;++ (global.fetch as any).mockResolvedValueOnce({+ ok: true,+ status: 207,+ text: async () => mockXml+ });++ const items = await provider.list();+ expect(items.length).toBe(2);++ const file = items.find((i) => i.type === "file");+ const folder = items.find((i) => i.type === "folder");++ expect(file?.name).toBe("report.pdf");+ expect(file?.path).toBe("report.pdf"); // virtual path+ expect(file?.size).toBe(8192);+ expect(file?.mimeType).toBe("application/pdf");++ expect(folder?.name).toBe("Archive");+ expect(folder?.path).toBe("Archive"); // virtual path+ });+});diff --git a/packages/webdav/tsconfig.json b/packages/webdav/tsconfig.jsonnew file mode 100644index 0000000..134f8ff--- /dev/null+++ b/packages/webdav/tsconfig.json@@ -0,0 +1,13 @@+{+ "extends": "../../tsconfig.base.json",+ "compilerOptions": {+ "rootDir": "src",+ "outDir": "dist",+ "composite": true,+ "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"+ },+ "references": [+ { "path": "../core" }+ ],+ "include": ["src/**/*"]+}diff --git a/python/LICENSE b/python/LICENSEnew file mode 100644index 0000000..45654bb--- /dev/null+++ b/python/LICENSE@@ -0,0 +1,175 @@+ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work.++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONSdiff --git a/python/README.md b/python/README.mdnew file mode 100644index 0000000..22c8a90--- /dev/null+++ b/python/README.md@@ -0,0 +1,120 @@+# byoc-storage++[](https://pypi.org/project/byoc-storage/)+[](https://pypi.org/project/byoc-storage/)+[](https://github.com/Ajayvarmaramineni/BYOC)+[](https://github.com/Ajayvarmaramineni/BYOC)+[](https://github.com/Ajayvarmaramineni/BYOC/blob/main/LICENSE)++Python SDK for **BYOC (Bring Your Own Cloud)**: one storage API for Google Drive, Nextcloud, and S3-compatible clouds, so files live in accounts the end user already owns.++> Part of the [BYOC monorepo](https://github.com/Ajayvarmaramineni/BYOC). Peer implementation of [`@byoc/core`](https://www.npmjs.com/package/@byoc/core) on npm, verified interoperable by an automated cross-SDK suite.++## Why++Rather than paying to host every file in one central bucket, BYOC lets an application read and write storage the end user already owns: a personal Google Drive, a company Nextcloud, an organization's own R2 bucket.++```text+FastAPI / Django / Celery+ │+ ├── PostgreSQL → users, jobs, metadata pointers+ │+ └── byoc → the actual PDFs, images, audio, model artifacts+ │+ └── the user's own cloud+```++Use Postgres for application data. Use BYOC for the user's files.++## Install++```bash+pip install byoc-storage+```++The distribution is named `byoc-storage` because `byoc` on PyPI belongs to an+unrelated CLI framework. The import name is still `byoc`:++```python+import byoc+```++> If you also depend on the unrelated `byoc` CLI framework, do not install both+> into the same environment: they share the `byoc` import name and will shadow+> each other.++## Usage++```python+import os+from byoc import AsyncBYOC+from byoc.providers.s3 import S3CompatibleProvider++storage = AsyncBYOC(+ provider=S3CompatibleProvider(+ endpoint="https://<account_id>.r2.cloudflarestorage.com",+ bucket="user-assets",+ region="auto",+ access_key_id=os.environ["R2_ACCESS_KEY_ID"],+ secret_access_key=os.environ["R2_SECRET_ACCESS_KEY"],+ )+)++async with storage:+ await storage.write_text("documents/welcome.md", "# Hello from BYOC!")+ content = await storage.read_text("documents/welcome.md")+```++### Multiple providers and migration++```python+storage = AsyncBYOC(providers=[drive, r2, nextcloud], default_provider_id="s3-compatible")++storage.use_provider("webdav")+await storage.write_bytes("images/banner.png", data)++report = await storage.migrate(+ source="s3-compatible",+ target="webdav",+ paths=["documents/report.pdf"],+ on_progress=lambda p: print(f"{p.current_file} ({p.percentage}%)"),+)+```++`report.files_partial` counts files that reached the target but whose source+cleanup failed. The transfer is done, so retrying those would re-upload for+nothing.++> **Async only for now.** A synchronous facade for Celery, Django, and scripts+> is planned but not yet implemented; use `asyncio.run()` in the meantime.++## Google Drive++Drive needs a Google Cloud OAuth client. See [**Google Drive OAuth Setup**](https://github.com/Ajayvarmaramineni/BYOC/blob/main/docs/google-oauth-setup.md), then verify your setup with:++```bash+.venv/bin/python scripts/validate_gdrive_live.py+```++## Cross-SDK compatibility++This SDK and the TypeScript SDK are peer implementations of the same contract. Both run against the shared conformance vectors in [`spec/fixtures`](https://github.com/Ajayvarmaramineni/BYOC/blob/main/spec), so a file written by a Next.js frontend can be read by a FastAPI backend, including client-side encrypted files, whose envelope format is byte-identical across both.++## Development++```bash+python3 -m venv .venv+source .venv/bin/activate+pip install -e ".[dev]"++pytest # unit + conformance suite+mypy src # strict type checking+ruff check . # lint+```++Without activating, call the venv binaries directly: `.venv/bin/pytest`,+`.venv/bin/mypy src`, `.venv/bin/ruff check .`++## License++[Apache-2.0](https://github.com/Ajayvarmaramineni/BYOC/blob/main/LICENSE)diff --git a/python/pyproject.toml b/python/pyproject.tomlnew file mode 100644index 0000000..66b8ebb--- /dev/null+++ b/python/pyproject.toml@@ -0,0 +1,71 @@+[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"++[project]+name = "byoc-storage"+version = "0.2.0"+description = "BYOC (Bring Your Own Cloud) — universal storage abstraction for storage your users already own"+readme = "README.md"+requires-python = ">=3.10"+license = { file = "LICENSE" }+authors = [{ name = "Ajay Ramineni" }]+keywords = ["byoc", "cloud-storage", "google-drive", "s3", "webdav", "storage-abstraction"]+classifiers = [+ "Development Status :: 4 - Beta",+ "Intended Audience :: Developers",+ "License :: OSI Approved :: Apache Software License",+ "Programming Language :: Python :: 3.10",+ "Programming Language :: Python :: 3.11",+ "Programming Language :: Python :: 3.12",+ "Programming Language :: Python :: 3.13",+ "Typing :: Typed",+]+dependencies = [+ "httpx>=0.27",+ "cryptography>=42.0",+]++[project.optional-dependencies]+dev = [+ "pytest>=8.0",+ "pytest-asyncio>=0.23",+ "pytest-httpx>=0.30",+ "wsgidav>=4.3",+ "cheroot>=10.0",+ "mypy>=1.9",+ "ruff>=0.4",+]++[project.urls]+Homepage = "https://github.com/Ajayvarmaramineni/BYOC"+Repository = "https://github.com/Ajayvarmaramineni/BYOC"+Issues = "https://github.com/Ajayvarmaramineni/BYOC/issues"++[tool.hatch.build.targets.wheel]+packages = ["src/byoc"]++[tool.pytest.ini_options]+testpaths = ["tests"]+asyncio_mode = "auto"+# Import the package straight from the source tree rather than relying on an+# editable install. Editable-install .pth handling varies across Python+# versions, and the test run should not depend on it.+pythonpath = ["src", "tests"]+markers = [+ "integration: needs a live storage server (MinIO, Nextcloud); skipped when unreachable",+ "interop: runs both SDKs against the same server; needs node and a built TypeScript dist/",+]++[tool.mypy]+python_version = "3.10"+strict = true+warn_unreachable = true+disallow_any_explicit = false++[tool.ruff]+line-length = 100+target-version = "py310"++[tool.ruff.lint]+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]diff --git a/python/scripts/validate_gdrive_live.py b/python/scripts/validate_gdrive_live.pynew file mode 100644index 0000000..2a84ff4--- /dev/null+++ b/python/scripts/validate_gdrive_live.py@@ -0,0 +1,238 @@+#!/usr/bin/env python3+"""Manual live validation for the Google Drive adapter.++Drive cannot be covered in CI: it needs a real Google account and a browser+consent step. This script is the substitute -- run it once before releasing, and+after any change to the Drive adapter, OAuth flow, or path resolver.++Setup+-----+1. Google Cloud console -> create a project -> enable the **Google Drive API**.+2. APIs & Services -> OAuth consent screen -> External -> add yourself as a+ test user. No verification is needed: BYOC uses the non-restricted+ ``drive.file`` scope.+3. Credentials -> Create OAuth client ID -> **Desktop app**.+4. Export the client id (and secret, for a Desktop client)::++ export BYOC_GDRIVE_CLIENT_ID="...apps.googleusercontent.com"+ export BYOC_GDRIVE_CLIENT_SECRET="..."++Then run::++ python scripts/validate_gdrive_live.py++It opens a consent page, writes and reads real files in a throwaway folder in+your Drive, and cleans up after itself.+"""++from __future__ import annotations++import asyncio+import os+import sys+import time+import uuid+import webbrowser+from http.server import BaseHTTPRequestHandler, HTTPServer+from threading import Thread+from urllib.parse import parse_qs, urlparse++sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))++from byoc import AsyncBYOC+from byoc.providers.gdrive import (+ GoogleDriveProvider,+ generate_code_challenge,+ generate_code_verifier,+ generate_oauth_state,+)++AUTH_TIMEOUT_SECONDS = 180+REDIRECT_PORT = 8765+REDIRECT_URI = f"http://localhost:{REDIRECT_PORT}/callback"++AWKWARD_FILENAMES = [+ "notes/Bob's Notes.pdf",+ "notes/draft#2.pdf",+ "notes/what?.txt",+ "docs/café/naïve.txt",+ "Q3 report/a b.pdf",+]++_received: dict[str, str] = {}+++class _CallbackHandler(BaseHTTPRequestHandler):+ def do_GET(self) -> None:+ params = parse_qs(urlparse(self.path).query)+ _received.update({k: v[0] for k, v in params.items()})+ self.send_response(200)+ self.send_header("Content-Type", "text/html")+ self.end_headers()+ self.wfile.write(b"<h2>BYOC: authorization received. You can close this tab.</h2>")++ def log_message(self, *args: object) -> None:+ pass # keep the console readable+++def _authorize(provider: GoogleDriveProvider, verifier: str, state: str) -> str:+ url = provider.oauth.get_authorization_url(+ state=state, code_challenge=generate_code_challenge(verifier), redirect_uri=REDIRECT_URI+ )+ try:+ server = HTTPServer(("localhost", REDIRECT_PORT), _CallbackHandler)+ except OSError as exc:+ # Almost always an earlier run of this script that never exited.+ raise SystemExit(+ f"\nCould not listen on port {REDIRECT_PORT}: {exc}\n"+ "An earlier run is probably still holding it. Free it with:\n"+ f" lsof -nP -iTCP:{REDIRECT_PORT} -sTCP:LISTEN\n"+ f" kill <PID>"+ ) from exc++ Thread(target=server.handle_request, daemon=True).start()++ print("\nOpening the Google consent screen...")+ print(f"If it does not open, visit:\n {url}\n")+ print(f"Waiting up to {AUTH_TIMEOUT_SECONDS}s for the redirect (Ctrl+C to abort)...")+ webbrowser.open(url)++ # Google can refuse before ever redirecting -- an unapproved test user, for+ # instance -- in which case the callback never fires. Time out rather than+ # waiting forever, and sleep between polls instead of spinning a core.+ deadline = time.monotonic() + AUTH_TIMEOUT_SECONDS+ while "code" not in _received and "error" not in _received:+ if time.monotonic() > deadline:+ server.server_close()+ raise SystemExit(+ f"\nTimed out after {AUTH_TIMEOUT_SECONDS}s with no redirect.\n"+ "Google most likely blocked the sign-in before redirecting. Check:\n"+ " - your account is listed under OAuth consent screen -> Test users\n"+ " - the app's publishing status is 'Testing'\n"+ " - the OAuth client is a 'Desktop app'"+ )+ time.sleep(0.2)+ server.server_close()++ if "error" in _received:+ raise SystemExit(f"Authorization failed: {_received['error']}")+ if _received.get("state") != state:+ raise SystemExit("State mismatch — possible CSRF. Aborting.")+ return _received["code"]+++def check(label: str, passed: bool, detail: str = "") -> bool:+ print(f" {'PASS' if passed else 'FAIL'} {label}{f' -- {detail}' if detail else ''}")+ return passed+++async def main() -> int:+ client_id = os.environ.get("BYOC_GDRIVE_CLIENT_ID")+ if not client_id:+ print("Set BYOC_GDRIVE_CLIENT_ID (see this file's docstring for setup).")+ return 2++ run_folder = f"BYOC-validation-{uuid.uuid4().hex[:8]}"+ provider = GoogleDriveProvider(+ client_id=client_id,+ client_secret=os.environ.get("BYOC_GDRIVE_CLIENT_SECRET"),+ redirect_uri=REDIRECT_URI,+ root_folder_name=run_folder,+ )++ verifier = generate_code_verifier(64)+ code = _authorize(provider, verifier, generate_oauth_state(32))+ session = await provider.oauth.exchange_code(+ code=code, code_verifier=verifier, redirect_uri=REDIRECT_URI+ )++ results: list[bool] = []+ print("\nRunning live checks against your Drive...\n")++ results.append(+ check("OAuth returned a refresh token", session.refresh_token is not None,+ "without one the session dies in an hour")+ )++ storage = AsyncBYOC(provider=provider)+ await storage.connect()+ results.append(check("connect() created the app root folder", True, run_folder))++ try:+ obj = await storage.write_text("docs/hello.md", "# Hello from BYOC")+ results.append(+ check("upload returns a virtual path", obj.path == "docs/hello.md", obj.path)+ )++ text = await storage.read_text("docs/hello.md")+ results.append(check("download round-trip", text == "# Hello from BYOC"))++ meta = await storage.metadata("docs/hello.md")+ results.append(check("metadata reports a size", (meta.size or 0) > 0, str(meta.size)))++ for name in AWKWARD_FILENAMES:+ await storage.write_text(name, f"content of {name}")+ back = await storage.read_text(name)+ results.append(check(f"round-trip {name!r}", back == f"content of {name}"))++ listed = await storage.list("notes")+ results.append(+ check("list returns the notes folder contents", len(listed) >= 3,+ ", ".join(sorted(o.name for o in listed)))+ )++ quota = await storage.get_quota()+ results.append(check("quota reports usage", quota.used > 0, f"{quota.used} bytes used"))++ # Force a genuinely multi-chunk upload. A 6 MiB payload under the 8 MiB+ # default would go up in one chunk, leaving the 308 Resume Incomplete+ # loop and Range-header parsing -- the actually tricky part -- untested.+ chunk_size = 256 * 1024+ big = b"x" * (6 * 1024 * 1024)+ expected_chunks = -(-len(big) // chunk_size)+ seen: list[int] = []+ from byoc.types import UploadOptions++ await storage.upload(+ "large/blob.bin",+ big,+ UploadOptions(+ resumable=True,+ chunk_size=chunk_size,+ on_progress=lambda p: seen.append(p.bytes_uploaded),+ ),+ )+ results.append(+ check(+ f"resumable upload of 6 MiB in {chunk_size // 1024} KiB chunks",+ len(seen) >= expected_chunks - 1,+ f"{len(seen)} progress events, expected ~{expected_chunks}",+ )+ )+ results.append(+ check("progress advances monotonically", seen == sorted(seen), f"last={seen[-1]}")+ )+ results.append(+ check("resumable content round-trip", await storage.read_bytes("large/blob.bin") == big)+ )++ await storage.delete("docs/hello.md")+ results.append(check("delete removes the file", not await storage.exists("docs/hello.md")))++ finally:+ print("\nCleaning up...")+ for name in [*AWKWARD_FILENAMES, "large/blob.bin"]:+ try:+ await storage.delete(name)+ except Exception as exc:+ print(f" could not delete {name}: {exc}")+ print(f" NOTE: remove the '{run_folder}' folder from your Drive manually.")+ await storage.disconnect()++ passed = sum(results)+ print(f"\n{passed}/{len(results)} checks passed")+ return 0 if passed == len(results) else 1+++if __name__ == "__main__":+ raise SystemExit(asyncio.run(main()))diff --git a/python/src/byoc/__init__.py b/python/src/byoc/__init__.pynew file mode 100644index 0000000..df88bb0--- /dev/null+++ b/python/src/byoc/__init__.py@@ -0,0 +1,121 @@+"""BYOC (Bring Your Own Cloud) — universal storage abstraction for Python.++Peer implementation of the TypeScript ``@byoc/core`` SDK. Both run against the+shared conformance vectors in ``spec/fixtures``, so files written by one are+readable by the other -- including client-side encrypted files.+"""++from __future__ import annotations++from .client import AsyncBYOC, lookup_mime_type+from .encryption import E2EECrypto+from .errors import (+ AuthRequiredError,+ BYOCErrorCode,+ CapabilityUnsupportedError,+ ConflictError,+ CorruptedDataError,+ DownloadFailedError,+ InvalidInputError,+ ObjectAlreadyExistsError,+ ObjectNotFoundError,+ PermissionDeniedError,+ ProviderUnavailableError,+ QuotaExceededError,+ RateLimitedError,+ StorageError,+ TokenExpiredError,+ UploadFailedError,+)+from .logging import BYOCLogger, SafeLogger, SilentLogger, sanitize+from .migration import (+ MigrationFileResult,+ MigrationProgress,+ MigrationReport,+ migrate,+)+from .paths import (+ encode_path_segments,+ get_basename,+ get_dirname,+ normalize_virtual_path,+ rfc3986_uri_encode,+ split_path,+)+from .providers.gdrive import (+ GoogleDriveProvider,+ GoogleDriveScope,+)+from .retry import with_retry+from .types import (+ AuthType,+ BackupOptions,+ BYOCProvider,+ ConflictStrategy,+ ObjectType,+ ProviderCapabilities,+ ProviderCategory,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+ UploadProgress,+)++__version__ = "0.2.0"++__all__ = [+ "AsyncBYOC",+ "AuthRequiredError",+ "AuthType",+ "BYOCErrorCode",+ "BYOCLogger",+ "BYOCProvider",+ "BackupOptions",+ "CapabilityUnsupportedError",+ "ConflictError",+ "ConflictStrategy",+ "CorruptedDataError",+ "DownloadFailedError",+ "E2EECrypto",+ "GoogleDriveProvider",+ "GoogleDriveScope",+ "InvalidInputError",+ "MigrationFileResult",+ "MigrationProgress",+ "MigrationReport",+ "ObjectAlreadyExistsError",+ "ObjectNotFoundError",+ "ObjectType",+ "PermissionDeniedError",+ "ProviderCapabilities",+ "ProviderCategory",+ "ProviderManifest",+ "ProviderUnavailableError",+ "QuotaExceededError",+ "RateLimitedError",+ "SafeLogger",+ "SilentLogger",+ "StorageError",+ "StorageInput",+ "StorageObject",+ "StorageOutput",+ "StorageQuota",+ "TokenExpiredError",+ "UploadFailedError",+ "UploadOptions",+ "UploadProgress",+ "__version__",+ "encode_path_segments",+ "get_basename",+ "get_dirname",+ "lookup_mime_type",+ "migrate",+ "normalize_virtual_path",+ "rfc3986_uri_encode",+ "sanitize",+ "split_path",+ "with_retry",+]diff --git a/python/src/byoc/client.py b/python/src/byoc/client.pynew file mode 100644index 0000000..0b9b374--- /dev/null+++ b/python/src/byoc/client.py@@ -0,0 +1,336 @@+"""The universal BYOC client.++Applications talk to :class:`AsyncBYOC`; it routes to whichever provider adapter+is active. Provider-specific concepts -- Drive file IDs, S3 keys, WebDAV+collections -- never surface here.+"""++from __future__ import annotations++import mimetypes+from collections.abc import Sequence+from datetime import datetime, timezone++from .errors import CapabilityUnsupportedError, InvalidInputError+from .logging import BYOCLogger, SilentLogger+from .migration import MigrationReport, ProgressCallback, migrate+from .paths import normalize_virtual_path+from .types import (+ BackupOptions,+ BYOCProvider,+ ConflictStrategy,+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+)++DEFAULT_MIME_TYPE = "application/octet-stream"+++def lookup_mime_type(path: str, fallback: str = DEFAULT_MIME_TYPE) -> str:+ """Guess a MIME type from a path, falling back rather than returning None."""+ guessed, _ = mimetypes.guess_type(path)+ return guessed or fallback+++class AsyncBYOC:+ """Universal client for user-owned, self-hosted, and multi-cloud storage.++ Args:+ provider: A single provider adapter.+ providers: Several adapters, for runtime switching and migration.+ default_provider_id: Which registered provider starts active.+ logger: Where to log. Defaults to silent so importing BYOC is quiet.+ max_file_size_bytes: Reject in-memory uploads larger than this.++ At least one of ``provider`` or ``providers`` is required.+ """++ def __init__(+ self,+ *,+ provider: BYOCProvider | None = None,+ providers: Sequence[BYOCProvider] | None = None,+ default_provider_id: str | None = None,+ logger: BYOCLogger | None = None,+ max_file_size_bytes: int | None = None,+ ) -> None:+ registry: dict[str, BYOCProvider] = {}+ ordered: list[BYOCProvider] = []++ for adapter in [*( [provider] if provider else [] ), *(providers or [])]:+ ordered.append(adapter)+ registry[adapter.manifest().id] = adapter++ if not ordered:+ raise InvalidInputError(+ "BYOC initialization failed: at least one provider adapter must be supplied.",+ provider="core",+ )++ self._registry = registry+ self._logger = logger or SilentLogger()+ self._max_file_size_bytes = max_file_size_bytes++ if default_provider_id and default_provider_id in registry:+ self._current = registry[default_provider_id]+ else:+ self._current = ordered[0]++ # -- provider selection -------------------------------------------------++ def use_provider(self, provider_id: str) -> AsyncBYOC:+ """Switch the active provider. Returns ``self`` so calls can chain."""+ target = self._registry.get(provider_id)+ if target is None:+ available = ", ".join(sorted(self._registry)) or "none"+ raise InvalidInputError(+ f"Provider '{provider_id}' is not registered in this BYOC client. "+ f"Available providers: [{available}]",+ provider="core",+ )+ self._current = target+ return self++ def get_providers(self) -> list[ProviderManifest]:+ """Manifests for every registered provider."""+ return [adapter.manifest() for adapter in self._registry.values()]++ def manifest(self) -> ProviderManifest:+ """Manifest of the active provider."""+ return self._current.manifest()++ def capabilities(self) -> ProviderCapabilities:+ """Capabilities of the active provider."""+ return self._current.capabilities()++ def has_capability(self, capability: str) -> bool:+ """Whether the active provider supports ``capability``."""+ return bool(getattr(self.capabilities(), capability, False))++ # -- lifecycle ----------------------------------------------------------++ async def connect(self) -> None:+ """Connect the active provider."""+ self._logger.debug("Connecting to provider: %s", self.manifest().id)+ await self._current.connect()++ async def disconnect(self) -> None:+ """Disconnect the active provider."""+ self._logger.debug("Disconnecting from provider: %s", self.manifest().id)+ await self._current.disconnect()++ async def connect_all(self) -> None:+ """Connect every registered provider, for multi-cloud use."""+ for adapter in self._registry.values():+ await adapter.connect()++ async def disconnect_all(self) -> None:+ """Disconnect every registered provider."""+ for adapter in self._registry.values():+ await adapter.disconnect()++ async def __aenter__(self) -> AsyncBYOC:+ await self.connect()+ return self++ async def __aexit__(self, *exc_info: object) -> None:+ await self.disconnect()++ # -- core operations ----------------------------------------------------++ def _require_path(self, path: str, operation: str) -> str:+ normalized = normalize_virtual_path(path)+ if not normalized:+ raise InvalidInputError(+ f"{operation} requires a valid non-empty file path.", provider=self.manifest().id+ )+ return normalized++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ """Upload ``data`` to ``path``, detecting the MIME type when not given."""+ normalized = self._require_path(path, "Upload")++ if self._max_file_size_bytes is not None:+ size: int | None = None+ if isinstance(data, str):+ size = len(data.encode("utf-8"))+ elif isinstance(data, bytes | bytearray | memoryview):+ size = len(bytes(data))+ if size is not None and size > self._max_file_size_bytes:+ raise InvalidInputError(+ f"File size ({size} bytes) exceeds the configured maximum of "+ f"{self._max_file_size_bytes} bytes.",+ provider=self.manifest().id,+ )++ resolved = options or UploadOptions()+ if resolved.mime_type is None:+ resolved = UploadOptions(+ mime_type=lookup_mime_type(normalized),+ resumable=resolved.resumable,+ chunk_size=resolved.chunk_size,+ on_progress=resolved.on_progress,+ metadata=resolved.metadata,+ )++ self._logger.debug("Uploading to %s on %s", normalized, self.manifest().id)+ return await self._current.upload(normalized, data, resolved)++ async def write_text(+ self, path: str, content: str, options: UploadOptions | None = None+ ) -> StorageObject:+ """Upload a UTF-8 string."""+ resolved = options or UploadOptions()+ if resolved.mime_type is None:+ mime = lookup_mime_type(normalize_virtual_path(path), "text/plain; charset=utf-8")+ resolved = UploadOptions(+ mime_type=mime,+ resumable=resolved.resumable,+ chunk_size=resolved.chunk_size,+ on_progress=resolved.on_progress,+ metadata=resolved.metadata,+ )+ return await self.upload(path, content, resolved)++ async def write_bytes(+ self, path: str, data: bytes, options: UploadOptions | None = None+ ) -> StorageObject:+ """Upload raw bytes."""+ return await self.upload(path, data, options)++ async def download(self, path: str) -> StorageOutput:+ """Download the object at ``path``."""+ return await self._current.download(self._require_path(path, "Download"))++ async def read_text(self, path: str, encoding: str = "utf-8") -> str:+ """Download and decode an object as text."""+ return await (await self.download(path)).text(encoding)++ async def read_bytes(self, path: str) -> bytes:+ """Download an object as raw bytes."""+ return await (await self.download(path)).read()++ async def delete(self, path: str) -> None:+ """Delete the object at ``path``."""+ await self._current.delete(self._require_path(path, "Delete"))++ async def list(self, path: str | None = None) -> list[StorageObject]:+ """List objects under ``path``, or under the root if omitted."""+ return await self._current.list(normalize_virtual_path(path) or None)++ async def exists(self, path: str) -> bool:+ """Whether an object exists at ``path``. An empty path is never a file."""+ normalized = normalize_virtual_path(path)+ if not normalized:+ return False+ return await self._current.exists(normalized)++ async def metadata(self, path: str) -> StorageObject:+ """Metadata for the object at ``path``."""+ return await self._current.metadata(self._require_path(path, "Metadata lookup"))++ # -- capability-gated operations ---------------------------------------++ async def create_folder(self, path: str) -> StorageObject:+ """Create a folder, if the active provider has real folders."""+ create = getattr(self._current, "create_folder", None)+ if not self.capabilities().folders or create is None:+ raise CapabilityUnsupportedError(+ f"Provider '{self.manifest().name}' does not support explicit folder creation.",+ provider=self.manifest().id,+ )+ result: StorageObject = await create(self._require_path(path, "Create folder"))+ return result++ async def move(self, source: str, destination: str) -> None:+ """Move an object, if the active provider supports it natively."""+ mover = getattr(self._current, "move", None)+ if mover is None:+ raise CapabilityUnsupportedError(+ f"Provider '{self.manifest().name}' does not support native move operations.",+ provider=self.manifest().id,+ )+ await mover(+ self._require_path(source, "Move"), self._require_path(destination, "Move")+ )++ async def get_quota(self) -> StorageQuota:+ """Report storage quota, if the active provider exposes it."""+ quota = getattr(self._current, "quota", None)+ if not self.capabilities().quota or quota is None:+ raise CapabilityUnsupportedError(+ f"Provider '{self.manifest().name}' does not support quota reporting.",+ provider=self.manifest().id,+ )+ result: StorageQuota = await quota()+ return result++ # -- high-level helpers -------------------------------------------------++ async def backup(+ self, payload: StorageInput, options: BackupOptions | None = None+ ) -> StorageObject:+ """Write a timestamped backup file, defaulting to a ``Backups`` folder."""+ resolved = options or BackupOptions()+ folder = normalize_virtual_path(resolved.folder or "Backups")+ stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%S")+ filename = resolved.filename or f"backup-{stamp}.json"+ target = f"{folder}/{filename}" if folder else filename++ return await self.upload(+ target,+ payload,+ UploadOptions(+ mime_type=resolved.mime_type or "application/json",+ on_progress=resolved.on_progress,+ ),+ )++ async def migrate(+ self,+ *,+ source: str,+ target: str,+ paths: Sequence[str],+ conflict_strategy: ConflictStrategy = ConflictStrategy.OVERWRITE,+ concurrency: int = 4,+ delete_source_after_migrate: bool = False,+ on_progress: ProgressCallback | None = None,+ ) -> MigrationReport:+ """Transfer files between two registered providers.++ Args:+ source: Registered provider id to read from.+ target: Registered provider id to write to.+ """+ source_adapter = self._registry.get(source)+ target_adapter = self._registry.get(target)++ if source_adapter is None:+ raise InvalidInputError(+ f"Source provider '{source}' is not registered in this BYOC client.",+ provider="core",+ )+ if target_adapter is None:+ raise InvalidInputError(+ f"Destination provider '{target}' is not registered in this BYOC client.",+ provider="core",+ )++ return await migrate(+ source=source_adapter,+ target=target_adapter,+ paths=paths,+ conflict_strategy=conflict_strategy,+ concurrency=concurrency,+ delete_source_after_migrate=delete_source_after_migrate,+ on_progress=on_progress,+ logger=self._logger,+ )diff --git a/python/src/byoc/encryption.py b/python/src/byoc/encryption.pynew file mode 100644index 0000000..7364192--- /dev/null+++ b/python/src/byoc/encryption.py@@ -0,0 +1,175 @@+"""Client-side end-to-end encryption.++The envelope written here is a binary format stored in the user's own cloud and+read back by any BYOC SDK in any language, so its layout is cross-SDK contract.+It is pinned by ``spec/fixtures/e2ee-envelope.json``::++ V2: MAGIC(12) | ITER(4) | SALT(16) | IV(12) | TAG(16) | CIPHERTEXT(n)+ V1: MAGIC(12) | SALT(16) | IV(12) | TAG(16) | CIPHERTEXT(n)++Cipher is AES-256-GCM; the key is PBKDF2-HMAC-SHA256(passphrase, salt,+iterations, dklen=32). The magic header, iteration field and salt are bound as+GCM additional authenticated data, so the header cannot be edited undetected.+"""++from __future__ import annotations++import asyncio+import hashlib+import os++from cryptography.exceptions import InvalidTag+from cryptography.hazmat.primitives.ciphers.aead import AESGCM++from .errors import AuthRequiredError, CorruptedDataError, InvalidInputError++E2EE_MAGIC_HEADER_V1 = b"BYOC_E2EE_V1" # legacy v0.1 format, fixed 100k iterations+E2EE_MAGIC_HEADER_V2 = b"BYOC_E2EE_V2" # v0.2 format, 4-byte iteration field+MAGIC_LENGTH = 12+ITER_LENGTH = 4+SALT_LENGTH = 16+IV_LENGTH = 12+TAG_LENGTH = 16++HEADER_LENGTH_V1 = MAGIC_LENGTH + SALT_LENGTH + IV_LENGTH + TAG_LENGTH+HEADER_LENGTH_V2 = MAGIC_LENGTH + ITER_LENGTH + SALT_LENGTH + IV_LENGTH + TAG_LENGTH++V1_FIXED_ITERATIONS = 100_000+DEFAULT_ITERATIONS = 600_000++# Accepted bounds for the envelope-encoded PBKDF2 iteration count.+#+# The iteration count is read from untrusted storage and consumed *before* the+# GCM tag can authenticate it, so it must be range-checked first: a hostile+# 4-byte edit would otherwise turn a ~50 ms decrypt into minutes of PBKDF2+# occupying a worker thread. The floor rejects envelopes whose key derivation is+# too weak to trust; the ceiling caps the work an attacker can force.+MIN_ITERATIONS = 10_000+MAX_ITERATIONS = 2_000_000+++class E2EECrypto:+ """Encrypts and decrypts payloads with AES-256-GCM and a PBKDF2-derived key.++ Args:+ passphrase: User passphrase to derive the key from.+ master_key: Raw key material, as an alternative to ``passphrase``.+ key_derivation_iterations: PBKDF2 iteration count for *new* envelopes.+ Must fall within ``MIN_ITERATIONS``..``MAX_ITERATIONS``. Decryption+ always honours the count recorded in the file being read, so raising+ this never orphans existing data.+ """++ def __init__(+ self,+ *,+ passphrase: str | None = None,+ master_key: bytes | None = None,+ key_derivation_iterations: int = DEFAULT_ITERATIONS,+ ) -> None:+ if passphrase is None and master_key is None:+ raise InvalidInputError(+ "E2EECrypto requires either a 'passphrase' or 'master_key'.", provider="core"+ )++ if not MIN_ITERATIONS <= key_derivation_iterations <= MAX_ITERATIONS:+ raise InvalidInputError(+ f"E2EECrypto 'key_derivation_iterations' must be between {MIN_ITERATIONS} "+ f"and {MAX_ITERATIONS} (received {key_derivation_iterations}).",+ provider="core",+ )++ self.iterations = key_derivation_iterations+ self._master_key = (+ bytes(master_key) if master_key is not None else passphrase.encode("utf-8") # type: ignore[union-attr]+ )++ def _derive_key(self, salt: bytes, iterations: int) -> bytes:+ return hashlib.pbkdf2_hmac("sha256", self._master_key, salt, iterations, dklen=32)++ def encrypt_sync(self, plaintext: bytes | str) -> bytes:+ """Encrypt to a V2 envelope. Blocking; prefer :meth:`encrypt` in async code."""+ data = plaintext.encode("utf-8") if isinstance(plaintext, str) else bytes(plaintext)+ salt = os.urandom(SALT_LENGTH)+ iv = os.urandom(IV_LENGTH)+ iter_field = self.iterations.to_bytes(ITER_LENGTH, "big")++ key = self._derive_key(salt, self.iterations)+ aad = E2EE_MAGIC_HEADER_V2 + iter_field + salt++ # AESGCM.encrypt returns ciphertext || tag; the envelope stores the tag+ # ahead of the ciphertext, so split them apart.+ sealed = AESGCM(key).encrypt(iv, data, aad)+ ciphertext, tag = sealed[:-TAG_LENGTH], sealed[-TAG_LENGTH:]++ return E2EE_MAGIC_HEADER_V2 + iter_field + salt + iv + tag + ciphertext++ def decrypt_sync(self, envelope: bytes) -> bytes:+ """Decrypt a V1 or V2 envelope. Blocking; prefer :meth:`decrypt` in async code."""+ buf = bytes(envelope)++ if len(buf) < HEADER_LENGTH_V1:+ raise CorruptedDataError(+ "Invalid E2EE payload: Data is shorter than header size.", provider="core"+ )++ magic = buf[:MAGIC_LENGTH]+ is_v2 = magic == E2EE_MAGIC_HEADER_V2+ is_v1 = magic == E2EE_MAGIC_HEADER_V1++ if not is_v2 and not is_v1:+ raise CorruptedDataError(+ "Invalid E2EE payload: Missing or unrecognized magic header.", provider="core"+ )++ offset = MAGIC_LENGTH++ if is_v2:+ if len(buf) < HEADER_LENGTH_V2:+ raise CorruptedDataError(+ "Invalid E2EE V2 payload: Data is shorter than header size.", provider="core"+ )++ iter_field = buf[offset : offset + ITER_LENGTH]+ file_iterations = int.from_bytes(iter_field, "big")++ # Range-check before deriving: this value comes from untrusted+ # storage and is consumed before the GCM tag can authenticate it.+ if not MIN_ITERATIONS <= file_iterations <= MAX_ITERATIONS:+ raise CorruptedDataError(+ f"Invalid E2EE payload: iteration count {file_iterations} is outside the "+ f"accepted range ({MIN_ITERATIONS}-{MAX_ITERATIONS}).",+ provider="core",+ )++ offset += ITER_LENGTH+ salt = buf[offset : offset + SALT_LENGTH]+ aad = E2EE_MAGIC_HEADER_V2 + iter_field + salt+ else:+ file_iterations = V1_FIXED_ITERATIONS+ salt = buf[offset : offset + SALT_LENGTH]+ aad = E2EE_MAGIC_HEADER_V1 + salt++ offset += SALT_LENGTH+ iv = buf[offset : offset + IV_LENGTH]+ offset += IV_LENGTH+ tag = buf[offset : offset + TAG_LENGTH]+ offset += TAG_LENGTH+ ciphertext = buf[offset:]++ try:+ key = self._derive_key(salt, file_iterations)+ return AESGCM(key).decrypt(iv, ciphertext + tag, aad)+ except InvalidTag as exc:+ raise AuthRequiredError(+ "E2EE Decryption failed: Invalid passphrase or corrupted ciphertext.",+ provider="core",+ ) from exc++ async def encrypt(self, plaintext: bytes | str) -> bytes:+ """Encrypt to a V2 envelope, deriving the key off the event loop."""+ return await asyncio.to_thread(self.encrypt_sync, plaintext)++ async def decrypt(self, envelope: bytes) -> bytes:+ """Decrypt a V1 or V2 envelope, deriving the key off the event loop."""+ return await asyncio.to_thread(self.decrypt_sync, envelope)diff --git a/python/src/byoc/errors.py b/python/src/byoc/errors.pynew file mode 100644index 0000000..2ccb756--- /dev/null+++ b/python/src/byoc/errors.py@@ -0,0 +1,187 @@+"""Provider-neutral error taxonomy.++The ``code`` strings are the cross-SDK contract and match the TypeScript+``BYOCErrorCode`` exactly -- conformance fixtures assert on them. The exception+*classes* are Python's own concern: callers should catch types, not compare+strings.+"""++from __future__ import annotations++from enum import Enum+from typing import Any+++class BYOCErrorCode(str, Enum):+ """Shared error codes. These strings are wire contract; do not rename.++ Subclasses ``str`` rather than using ``enum.StrEnum`` so the package still+ supports Python 3.10.+ """++ def __str__(self) -> str:+ return self.value++ AUTH_REQUIRED = "BYOC_AUTH_REQUIRED"+ OBJECT_NOT_FOUND = "BYOC_OBJECT_NOT_FOUND"+ PERMISSION_DENIED = "BYOC_PERMISSION_DENIED"+ QUOTA_EXCEEDED = "BYOC_QUOTA_EXCEEDED"+ RATE_LIMITED = "BYOC_RATE_LIMITED"+ UPLOAD_FAILED = "BYOC_UPLOAD_FAILED"+ DOWNLOAD_FAILED = "BYOC_DOWNLOAD_FAILED"+ PROVIDER_UNAVAILABLE = "BYOC_PROVIDER_UNAVAILABLE"+ TOKEN_EXPIRED = "BYOC_TOKEN_EXPIRED"+ CONFLICT = "BYOC_CONFLICT"+ OBJECT_ALREADY_EXISTS = "BYOC_OBJECT_ALREADY_EXISTS"+ CAPABILITY_UNSUPPORTED = "BYOC_CAPABILITY_UNSUPPORTED"+ INVALID_INPUT = "BYOC_INVALID_INPUT"+ CORRUPTED_DATA = "BYOC_CORRUPTED_DATA"+++class StorageError(Exception):+ """Base class for every BYOC error.++ Catch this to handle any storage failure; catch a subclass to handle one+ kind. ``code`` is the shared identifier used by the conformance fixtures.+ """++ code: BYOCErrorCode = BYOCErrorCode.PROVIDER_UNAVAILABLE++ def __init__(+ self,+ message: str,+ *,+ provider: str = "core",+ status_code: int | None = None,+ retryable: bool = False,+ raw_error: Any = None,+ code: BYOCErrorCode | None = None,+ ) -> None:+ super().__init__(message)+ self.message = message+ self.provider = provider+ self.status_code = status_code+ self.retryable = retryable+ self.raw_error = raw_error+ if code is not None:+ self.code = code++ def __str__(self) -> str:+ return f"[{self.code}] {self.message}"++ def __repr__(self) -> str:+ return (+ f"{type(self).__name__}(code={self.code!r}, provider={self.provider!r}, "+ f"message={self.message!r})"+ )+++class AuthRequiredError(StorageError):+ """Authentication is missing, invalid, or expired. Re-auth required."""++ code = BYOCErrorCode.AUTH_REQUIRED+++class ObjectNotFoundError(StorageError):+ """The requested object or folder path was not found."""++ code = BYOCErrorCode.OBJECT_NOT_FOUND+++class PermissionDeniedError(StorageError):+ """Permission denied by the provider (read-only access or insufficient scope)."""++ code = BYOCErrorCode.PERMISSION_DENIED+++class QuotaExceededError(StorageError):+ """The target cloud account has exceeded its storage quota."""++ code = BYOCErrorCode.QUOTA_EXCEEDED+++class RateLimitedError(StorageError):+ """Provider rate limit exceeded. Temporary and retryable."""++ code = BYOCErrorCode.RATE_LIMITED++ def __init__(self, message: str, **kwargs: Any) -> None:+ kwargs.setdefault("retryable", True)+ super().__init__(message, **kwargs)+++class UploadFailedError(StorageError):+ """Upload failed during binary transmission or chunk assembly."""++ code = BYOCErrorCode.UPLOAD_FAILED+++class DownloadFailedError(StorageError):+ """Download failed or the connection was severed during streaming."""++ code = BYOCErrorCode.DOWNLOAD_FAILED+++class ProviderUnavailableError(StorageError):+ """Provider service is down or temporarily unreachable."""++ code = BYOCErrorCode.PROVIDER_UNAVAILABLE+++class TokenExpiredError(StorageError):+ """Authentication token expired and refresh failed."""++ code = BYOCErrorCode.TOKEN_EXPIRED+++class ConflictError(StorageError):+ """Conflict detected, such as a naming clash or concurrent modification."""++ code = BYOCErrorCode.CONFLICT+++class ObjectAlreadyExistsError(StorageError):+ """The target object already exists on the destination provider."""++ code = BYOCErrorCode.OBJECT_ALREADY_EXISTS+++class CapabilityUnsupportedError(StorageError):+ """The connected provider does not support the requested operation."""++ code = BYOCErrorCode.CAPABILITY_UNSUPPORTED+++class InvalidInputError(StorageError):+ """Input validation failed, such as an invalid virtual path."""++ code = BYOCErrorCode.INVALID_INPUT+++class CorruptedDataError(StorageError):+ """Ciphertext payload or metadata is corrupted or malformed."""++ code = BYOCErrorCode.CORRUPTED_DATA+++ERROR_CLASS_BY_CODE: dict[BYOCErrorCode, type[StorageError]] = {+ BYOCErrorCode.AUTH_REQUIRED: AuthRequiredError,+ BYOCErrorCode.OBJECT_NOT_FOUND: ObjectNotFoundError,+ BYOCErrorCode.PERMISSION_DENIED: PermissionDeniedError,+ BYOCErrorCode.QUOTA_EXCEEDED: QuotaExceededError,+ BYOCErrorCode.RATE_LIMITED: RateLimitedError,+ BYOCErrorCode.UPLOAD_FAILED: UploadFailedError,+ BYOCErrorCode.DOWNLOAD_FAILED: DownloadFailedError,+ BYOCErrorCode.PROVIDER_UNAVAILABLE: ProviderUnavailableError,+ BYOCErrorCode.TOKEN_EXPIRED: TokenExpiredError,+ BYOCErrorCode.CONFLICT: ConflictError,+ BYOCErrorCode.OBJECT_ALREADY_EXISTS: ObjectAlreadyExistsError,+ BYOCErrorCode.CAPABILITY_UNSUPPORTED: CapabilityUnsupportedError,+ BYOCErrorCode.INVALID_INPUT: InvalidInputError,+ BYOCErrorCode.CORRUPTED_DATA: CorruptedDataError,+}+"""Maps a shared error code to its Python exception class.++Used by the conformance suite, which asserts on codes, and by provider adapters+mapping a remote error response onto the right exception type.+"""diff --git a/python/src/byoc/logging.py b/python/src/byoc/logging.pynew file mode 100644index 0000000..3b848d3--- /dev/null+++ b/python/src/byoc/logging.py@@ -0,0 +1,98 @@+"""Logging that redacts credentials before they reach a handler.++BYOC handles OAuth tokens, refresh tokens and cloud access keys, so anything+that might carry one is scrubbed on the way out. A leaked token in an aggregated+log is a real compromise, not a cosmetic problem.+"""++from __future__ import annotations++import logging+import re+from typing import Any, Protocol++REDACTED = "[REDACTED_SECRET]"++_SENSITIVE_PATTERNS = [+ re.compile(r"Bearer\s+[A-Za-z0-9_\-.]+", re.IGNORECASE),+ re.compile(r"ya29\.[A-Za-z0-9_\-.]+", re.IGNORECASE),+ re.compile(+ r"(\"?(?:access_token|refresh_token|client_secret|api_key|apikey|secret|"+ r"authorization|password)\"?\s*[:=]\s*\"?[^\",\s}]+\"?)",+ re.IGNORECASE,+ ),+]++_SENSITIVE_KEY_HINTS = ("token", "secret", "password", "authorization", "credential", "api_key")+++def sanitize(value: Any) -> Any:+ """Recursively redact secrets from strings, mappings and sequences.++ Mapping keys are matched by name as well as value, because a credential+ stored under an obvious key often would not match the value patterns.+ """+ if isinstance(value, str):+ cleaned = value+ for pattern in _SENSITIVE_PATTERNS:+ cleaned = pattern.sub(REDACTED, cleaned)+ return cleaned++ if isinstance(value, dict):+ result: dict[Any, Any] = {}+ for key, item in value.items():+ if isinstance(key, str) and any(h in key.lower() for h in _SENSITIVE_KEY_HINTS):+ result[key] = REDACTED+ else:+ result[key] = sanitize(item)+ return result++ if isinstance(value, list | tuple | set):+ return type(value)(sanitize(item) for item in value)++ if isinstance(value, BaseException):+ return {"type": type(value).__name__, "message": sanitize(str(value))}++ return value+++class BYOCLogger(Protocol):+ """Minimal logging surface BYOC depends on."""++ def debug(self, message: str, *args: Any) -> None: ...+ def info(self, message: str, *args: Any) -> None: ...+ def warning(self, message: str, *args: Any) -> None: ...+ def error(self, message: str, *args: Any) -> None: ...+++class SafeLogger:+ """Wraps a :mod:`logging` logger and sanitizes every message and argument."""++ def __init__(self, name: str = "byoc", level: int = logging.INFO) -> None:+ self._logger = logging.getLogger(name)+ self._logger.setLevel(level)++ def _emit(self, level: int, message: str, args: tuple[Any, ...]) -> None:+ if self._logger.isEnabledFor(level):+ self._logger.log(level, str(sanitize(message)), *(sanitize(a) for a in args))++ def debug(self, message: str, *args: Any) -> None:+ self._emit(logging.DEBUG, message, args)++ def info(self, message: str, *args: Any) -> None:+ self._emit(logging.INFO, message, args)++ def warning(self, message: str, *args: Any) -> None:+ self._emit(logging.WARNING, message, args)++ def error(self, message: str, *args: Any) -> None:+ self._emit(logging.ERROR, message, args)+++class SilentLogger:+ """Discards everything. The default, so importing BYOC never adds log noise."""++ def debug(self, message: str, *args: Any) -> None: ...+ def info(self, message: str, *args: Any) -> None: ...+ def warning(self, message: str, *args: Any) -> None: ...+ def error(self, message: str, *args: Any) -> None: ...diff --git a/python/src/byoc/migration.py b/python/src/byoc/migration.pynew file mode 100644index 0000000..db5e639--- /dev/null+++ b/python/src/byoc/migration.py@@ -0,0 +1,199 @@+"""Transfer files between any two registered providers.++Mirrors the semantics of the TypeScript ``MigrationEngine``, including the+``partial`` outcome: if the copy to the target succeeded but the optional source+deletion failed, the transfer is done and only cleanup remains. Reporting that+as ``failed`` would make a caller re-upload bytes that are already there.+"""++from __future__ import annotations++import asyncio+from collections.abc import Callable, Sequence+from dataclasses import dataclass, field+from typing import Literal++from .errors import InvalidInputError, ObjectAlreadyExistsError, StorageError+from .logging import BYOCLogger, SilentLogger+from .paths import normalize_virtual_path+from .types import BYOCProvider, ConflictStrategy, UploadOptions++FileStatus = Literal["migrated", "skipped", "failed", "partial"]+++@dataclass(frozen=True, slots=True)+class MigrationFileResult:+ """Outcome for a single file.++ ``partial`` means the target copy exists but the source was not deleted.+ Callers retrying ``failed`` paths must not retry ``partial`` ones.+ """++ path: str+ status: FileStatus+ size: int | None = None+ error: str | None = None+++@dataclass(frozen=True, slots=True)+class MigrationProgress:+ """Emitted after each file finishes, whatever its outcome."""++ current_file: str+ files_migrated: int+ files_total: int+ bytes_transferred: int+ percentage: int+++@dataclass(frozen=True, slots=True)+class MigrationReport:+ """Summary of a completed migration."""++ source_provider: str+ target_provider: str+ files_total: int+ files_migrated: int+ files_skipped: int+ files_failed: int+ files_partial: int+ bytes_transferred: int+ results: list[MigrationFileResult] = field(default_factory=list)+++ProgressCallback = Callable[[MigrationProgress], None]+++async def migrate(+ *,+ source: BYOCProvider,+ target: BYOCProvider,+ paths: Sequence[str],+ conflict_strategy: ConflictStrategy = ConflictStrategy.OVERWRITE,+ concurrency: int = 4,+ delete_source_after_migrate: bool = False,+ on_progress: ProgressCallback | None = None,+ logger: BYOCLogger | None = None,+) -> MigrationReport:+ """Copy ``paths`` from ``source`` to ``target``.++ Args:+ conflict_strategy: What to do when the target already has the file.+ concurrency: How many files to transfer at once.+ delete_source_after_migrate: Delete each source file after a successful+ copy. A failure here yields ``partial``, never ``failed``.+ """+ log = logger or SilentLogger()++ if source is None or target is None:+ raise InvalidInputError(+ "Migration requires both 'source' and 'target' provider adapters.",+ provider="migration-engine",+ )++ clean_paths = [p for p in (normalize_virtual_path(path) for path in paths) if p]+ source_id = source.manifest().id+ target_id = target.manifest().id++ if not clean_paths:+ return MigrationReport(+ source_provider=source_id,+ target_provider=target_id,+ files_total=0,+ files_migrated=0,+ files_skipped=0,+ files_failed=0,+ files_partial=0,+ bytes_transferred=0,+ results=[],+ )++ results: list[MigrationFileResult] = []+ counts = {"migrated": 0, "skipped": 0, "failed": 0, "partial": 0}+ bytes_transferred = 0+ lock = asyncio.Lock()++ def emit(current_file: str) -> None:+ if on_progress is None:+ return+ finished = sum(counts.values())+ on_progress(+ MigrationProgress(+ current_file=current_file,+ files_migrated=counts["migrated"],+ files_total=len(clean_paths),+ bytes_transferred=bytes_transferred,+ percentage=round(finished / len(clean_paths) * 100),+ )+ )++ async def record(result: MigrationFileResult, transferred: int = 0) -> None:+ nonlocal bytes_transferred+ async with lock:+ counts[result.status] += 1+ bytes_transferred += transferred+ results.append(result)+ emit(result.path)++ semaphore = asyncio.Semaphore(max(1, concurrency))++ async def transfer(path: str) -> None:+ async with semaphore:+ try:+ overwriting = conflict_strategy is ConflictStrategy.OVERWRITE+ if not overwriting and await target.exists(path):+ if conflict_strategy is ConflictStrategy.SKIP:+ await record(MigrationFileResult(path=path, status="skipped"))+ return+ raise ObjectAlreadyExistsError(+ f'File already exists on target provider at path: "{path}"',+ provider=target_id,+ )++ output = await source.download(path)+ payload = await output.read()+ size = output.metadata.size if output.metadata.size is not None else len(payload)++ await target.upload(+ path, payload, UploadOptions(mime_type=output.metadata.mime_type)+ )++ # The bytes are on the target now. Anything that fails past this+ # point is cleanup, not transfer, and must not read as failure.+ if delete_source_after_migrate:+ try:+ await source.delete(path)+ except StorageError as exc:+ await record(+ MigrationFileResult(+ path=path,+ status="partial",+ size=size,+ error=f"Copied to target, but source deletion failed: {exc}",+ ),+ transferred=size,+ )+ return++ await record(+ MigrationFileResult(path=path, status="migrated", size=size),+ transferred=size,+ )++ except Exception as exc:+ await record(MigrationFileResult(path=path, status="failed", error=str(exc)))++ log.info("Starting migration from %s to %s (%d files)", source_id, target_id, len(clean_paths))+ await asyncio.gather(*(transfer(path) for path in clean_paths))++ return MigrationReport(+ source_provider=source_id,+ target_provider=target_id,+ files_total=len(clean_paths),+ files_migrated=counts["migrated"],+ files_skipped=counts["skipped"],+ files_failed=counts["failed"],+ files_partial=counts["partial"],+ bytes_transferred=bytes_transferred,+ results=results,+ )diff --git a/python/src/byoc/paths.py b/python/src/byoc/paths.pynew file mode 100644index 0000000..6d73d0e--- /dev/null+++ b/python/src/byoc/paths.py@@ -0,0 +1,125 @@+"""Virtual path normalization and RFC 3986 encoding.++These functions decide which folder bytes land in and what object key they are+stored under, so they are cross-SDK contract. Behaviour is pinned by+``spec/fixtures/path-normalization.json`` and ``spec/fixtures/path-encoding.json``+-- if a change here breaks those, the change is wrong.+"""++from __future__ import annotations++import re++from .errors import InvalidInputError++_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")+_MULTI_SLASH = re.compile(r"/+")++# RFC 3986 unreserved: ALPHA / DIGIT / "-" / "." / "_" / "~".+# Everything else is percent-encoded with uppercase hex.+_UNRESERVED = frozenset(+ "ABCDEFGHIJKLMNOPQRSTUVWXYZ" "abcdefghijklmnopqrstuvwxyz" "0123456789" "-._~"+)+++def normalize_virtual_path(raw_path: str | None = None) -> str:+ """Normalize a virtual path to a clean POSIX-style relative path.++ Converts backslashes to forward slashes, strips control characters, collapses+ duplicate slashes, trims surrounding whitespace and slashes, and drops ``.``+ segments. Returns ``""`` for the storage root.++ Raises:+ InvalidInputError: if the path contains a ``..`` traversal segment.+ """+ if not raw_path or not isinstance(raw_path, str):+ return ""++ # Strip control characters first: they are invisible and would otherwise+ # survive into a provider request.+ path = _CONTROL_CHARS.sub("", raw_path)+ path = path.strip().replace("\\", "/")+ path = _MULTI_SLASH.sub("/", path)+ path = path.strip("/")++ if not path:+ return ""++ clean_segments: list[str] = []+ for segment in path.split("/"):+ trimmed = segment.strip()++ if trimmed in ("", "."):+ continue++ if trimmed == "..":+ raise InvalidInputError(+ f'Invalid virtual path "{raw_path}": Directory traversal ("..") is forbidden.',+ provider="core",+ )++ clean_segments.append(trimmed)++ return "/".join(clean_segments)+++def get_basename(path: str) -> str:+ """Return the file or folder name from a path (``a/b/c.txt`` -> ``c.txt``)."""+ normalized = normalize_virtual_path(path)+ if not normalized:+ return ""+ _, _, last = normalized.rpartition("/")+ return last+++def get_dirname(path: str) -> str:+ """Return the parent directory of a path (``a/b/c.txt`` -> ``a/b``)."""+ normalized = normalize_virtual_path(path)+ if not normalized:+ return ""+ head, sep, _ = normalized.rpartition("/")+ return head if sep else ""+++def split_path(path: str) -> list[str]:+ """Split a path into segments (``a/b/c.txt`` -> ``["a", "b", "c.txt"]``)."""+ normalized = normalize_virtual_path(path)+ return normalized.split("/") if normalized else []+++def rfc3986_uri_encode(value: str, encode_slash: bool = False) -> str:+ """Percent-encode a string per RFC 3986.++ Only unreserved characters (``A-Za-z0-9-._~``) pass through; everything else+ becomes uppercase percent-escapes of its UTF-8 bytes.++ This deliberately does not use :func:`urllib.parse.quote`, whose default safe+ set differs -- notably it leaves ``/`` alone and treats different punctuation+ as safe than RFC 3986 does.++ Args:+ value: The string to encode.+ encode_slash: If ``True``, ``/`` is encoded as ``%2F``. If ``False``,+ forward slashes are preserved so path structure survives.+ """+ out: list[str] = []+ for char in value:+ if char in _UNRESERVED or (char == "/" and not encode_slash):+ out.append(char)+ else:+ out.extend(f"%{byte:02X}" for byte in char.encode("utf-8"))+ return "".join(out)+++def encode_path_segments(path: str) -> str:+ """Encode each path segment per RFC 3986, preserving the ``/`` hierarchy.++ Safely encodes ``#``, ``?``, ``&``, ``+``, spaces, and unicode without+ breaking the path structure. Leading and trailing slashes are trimmed;+ interior duplicate slashes are preserved, since collapsing them is+ :func:`normalize_virtual_path`'s job and encoding always runs after it.+ """+ clean = path.strip("/")+ if not clean:+ return ""+ return "/".join(rfc3986_uri_encode(segment, True) for segment in clean.split("/"))diff --git a/python/src/byoc/providers/__init__.py b/python/src/byoc/providers/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/python/src/byoc/providers/_sigv4.py b/python/src/byoc/providers/_sigv4.pynew file mode 100644index 0000000..f625f79--- /dev/null+++ b/python/src/byoc/providers/_sigv4.py@@ -0,0 +1,192 @@+"""AWS Signature Version 4 request signing.++Used by the S3-compatible adapter for AWS S3, Cloudflare R2, MinIO, and Wasabi.+Behaviour is pinned by ``spec/fixtures/sigv4.json``; the first vector there was+verified against a clean-room implementation written from the AWS specification,+so these are an external check rather than a snapshot of our own output.+"""++from __future__ import annotations++import hashlib+import hmac+import re+from datetime import datetime, timezone+from urllib.parse import parse_qsl, urlsplit, urlunsplit++from ..paths import rfc3986_uri_encode++ALGORITHM = "AWS4-HMAC-SHA256"+EMPTY_BODY_SHA256 = hashlib.sha256(b"").hexdigest()+UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD"++_WHITESPACE_RUN = re.compile(r"\s+")+++def _sha256_hex(data: bytes) -> str:+ return hashlib.sha256(data).hexdigest()+++def _hmac(key: bytes, message: str) -> bytes:+ return hmac.new(key, message.encode("utf-8"), hashlib.sha256).digest()+++def _signing_key(secret_access_key: str, date_stamp: str, region: str, service: str) -> bytes:+ k_date = _hmac(f"AWS4{secret_access_key}".encode(), date_stamp)+ k_region = _hmac(k_date, region)+ k_service = _hmac(k_region, service)+ return _hmac(k_service, "aws4_request")+++def build_canonical_query_string(query: str) -> str:+ """Build the SigV4 canonical query string.++ Each key and value is RFC 3986 encoded (slashes included), then pairs are+ sorted by encoded key and, on ties, by encoded value.++ A ``+`` in a raw query string decodes to a space and must re-encode as+ ``%20``; emitting ``+`` produces a signature AWS will reject.+ """+ pairs = [+ (rfc3986_uri_encode(key, True), rfc3986_uri_encode(value, True))+ for key, value in parse_qsl(query, keep_blank_values=True)+ ]+ pairs.sort()+ return "&".join(f"{key}={value}" for key, value in pairs)+++def _normalize_headers(headers: dict[str, str] | None) -> dict[str, str]:+ """Lowercase keys and trim/collapse whitespace in values.++ Signing a header under a different case than it is sent produces a+ signature mismatch, so normalization must happen before both.+ """+ normalized: dict[str, str] = {}+ for key, value in (headers or {}).items():+ normalized[key.lower().strip()] = _WHITESPACE_RUN.sub(" ", value.strip())+ return normalized+++def _amz_date(moment: datetime) -> str:+ return moment.astimezone(timezone.utc).strftime("%Y%m%dT%H%M%SZ")+++def sign_s3_request(+ *,+ access_key_id: str,+ secret_access_key: str,+ region: str,+ method: str,+ url: str,+ service: str = "s3",+ headers: dict[str, str] | None = None,+ body: bytes | None = None,+ moment: datetime | None = None,+) -> dict[str, str]:+ """Sign a request and return the headers to send, including ``Authorization``.++ The returned mapping is what must go on the wire: sending a header that was+ not signed, or with different casing, invalidates the signature.+ """+ now = moment or datetime.now(timezone.utc)+ amz_date = _amz_date(now)+ date_stamp = amz_date[:8]++ parts = urlsplit(url)+ canonical_uri = parts.path or "/"+ canonical_query = build_canonical_query_string(parts.query)++ # An empty body signs as the sha256 of the empty string, not UNSIGNED-PAYLOAD.+ body_hash = _sha256_hex(body) if body else EMPTY_BODY_SHA256++ signed = {+ "host": parts.netloc,+ "x-amz-date": amz_date,+ "x-amz-content-sha256": body_hash,+ **_normalize_headers(headers),+ }++ sorted_keys = sorted(signed)+ canonical_headers = "".join(f"{key}:{signed[key]}\n" for key in sorted_keys)+ signed_headers = ";".join(sorted_keys)++ canonical_request = "\n".join(+ [+ method.upper(),+ canonical_uri,+ canonical_query,+ canonical_headers,+ signed_headers,+ body_hash,+ ]+ )++ credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"+ string_to_sign = "\n".join(+ [ALGORITHM, amz_date, credential_scope, _sha256_hex(canonical_request.encode("utf-8"))]+ )++ key = _signing_key(secret_access_key, date_stamp, region, service)+ signature = hmac.new(key, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()++ authorization = (+ f"{ALGORITHM} Credential={access_key_id}/{credential_scope}, "+ f"SignedHeaders={signed_headers}, Signature={signature}"+ )+ return {**signed, "Authorization": authorization}+++def create_presigned_s3_url(+ *,+ access_key_id: str,+ secret_access_key: str,+ region: str,+ url: str,+ service: str = "s3",+ method: str = "GET",+ expires_in_seconds: int = 3600,+ moment: datetime | None = None,+) -> str:+ """Create a query-authenticated presigned URL.++ Presigned URLs sign ``UNSIGNED-PAYLOAD`` and only the ``host`` header, since+ the body is not known when the URL is created.+ """+ now = moment or datetime.now(timezone.utc)+ amz_date = _amz_date(now)+ date_stamp = amz_date[:8]+ credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"++ parts = urlsplit(url)+ query_pairs = parse_qsl(parts.query, keep_blank_values=True)+ query_pairs += [+ ("X-Amz-Algorithm", ALGORITHM),+ ("X-Amz-Credential", f"{access_key_id}/{credential_scope}"),+ ("X-Amz-Date", amz_date),+ ("X-Amz-Expires", str(expires_in_seconds)),+ ("X-Amz-SignedHeaders", "host"),+ ]+ query = "&".join(+ f"{rfc3986_uri_encode(k, True)}={rfc3986_uri_encode(v, True)}"+ for k, v in query_pairs+ )++ canonical_request = "\n".join(+ [+ method.upper(),+ parts.path or "/",+ build_canonical_query_string(query),+ f"host:{parts.netloc}\n",+ "host",+ UNSIGNED_PAYLOAD,+ ]+ )+ string_to_sign = "\n".join(+ [ALGORITHM, amz_date, credential_scope, _sha256_hex(canonical_request.encode("utf-8"))]+ )+ key = _signing_key(secret_access_key, date_stamp, region, service)+ signature = hmac.new(key, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()++ return urlunsplit(+ (parts.scheme, parts.netloc, parts.path, f"{query}&X-Amz-Signature={signature}", "")+ )diff --git a/python/src/byoc/providers/gdrive/__init__.py b/python/src/byoc/providers/gdrive/__init__.pynew file mode 100644index 0000000..72d3cf0--- /dev/null+++ b/python/src/byoc/providers/gdrive/__init__.py@@ -0,0 +1,42 @@+"""Google Drive provider for BYOC.++Stores your application's files in the Drive account the user already owns,+using the non-restricted ``drive.file`` scope.+"""++from __future__ import annotations++from ._http import DriveHttpClient+from ._oauth import GoogleDriveScope, GoogleOAuthClient+from ._pkce import generate_code_challenge, generate_code_verifier, generate_oauth_state+from ._resolver import (+ VIRTUAL_PATH_PROPERTY,+ DrivePathResolver,+ LruTtlPathCache,+ escape_drive_query_value,+)+from ._tokens import (+ EncryptedFileTokenStorage,+ InMemoryTokenStorage,+ TokenSession,+ TokenStorage,+)+from .adapter import GoogleDriveProvider++__all__ = [+ "VIRTUAL_PATH_PROPERTY",+ "DriveHttpClient",+ "DrivePathResolver",+ "EncryptedFileTokenStorage",+ "GoogleDriveProvider",+ "GoogleDriveScope",+ "GoogleOAuthClient",+ "InMemoryTokenStorage",+ "LruTtlPathCache",+ "TokenSession",+ "TokenStorage",+ "escape_drive_query_value",+ "generate_code_challenge",+ "generate_code_verifier",+ "generate_oauth_state",+]diff --git a/python/src/byoc/providers/gdrive/_http.py b/python/src/byoc/providers/gdrive/_http.pynew file mode 100644index 0000000..ab0e2f0--- /dev/null+++ b/python/src/byoc/providers/gdrive/_http.py@@ -0,0 +1,391 @@+"""Google Drive API v3 HTTP client.++Owns Drive's wire concerns: multipart and resumable upload framing, the+``fields`` projections, and mapping Drive's error shapes onto BYOC errors.+"""++from __future__ import annotations++import json+from collections.abc import AsyncIterator, Callable+from datetime import datetime+from typing import Any++import httpx++from ...errors import (+ AuthRequiredError,+ ObjectNotFoundError,+ PermissionDeniedError,+ ProviderUnavailableError,+ QuotaExceededError,+ RateLimitedError,+ StorageError,+)+from ...types import StorageObject, StorageQuota, UploadProgress+from ._resolver import FOLDER_MIME_TYPE, VIRTUAL_PATH_PROPERTY++API_BASE = "https://www.googleapis.com/drive/v3"+UPLOAD_BASE = "https://www.googleapis.com/upload/drive/v3"++FILE_FIELDS = (+ "id,name,mimeType,size,parents,createdTime,modifiedTime,md5Checksum,trashed,appProperties"+)++# Drive requires resumable chunks to be a multiple of 256 KiB (except the last).+CHUNK_ALIGNMENT = 256 * 1024+DEFAULT_CHUNK_SIZE = 8 * 1024 * 1024+# Above this, upload resumably so a dropped connection does not restart from zero.+RESUMABLE_THRESHOLD = 5 * 1024 * 1024+++def _parse_time(value: str | None) -> datetime | None:+ if not value:+ return None+ try:+ return datetime.fromisoformat(value.replace("Z", "+00:00"))+ except ValueError:+ return None+++class DriveHttpClient:+ """Authenticated Drive API client.++ Args:+ token_provider: Async callable returning a valid access token. Called+ per request so a refresh mid-session is picked up automatically.+ client: An ``httpx.AsyncClient`` to reuse.+ """++ def __init__(+ self,+ token_provider: Callable[[], Any],+ *,+ client: httpx.AsyncClient | None = None,+ ) -> None:+ self._token_provider = token_provider+ self._client = client+ self._owns_client = client is None++ def _http(self) -> httpx.AsyncClient:+ if self._client is None:+ self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0, read=300.0))+ self._owns_client = True+ return self._client++ async def aclose(self) -> None:+ if self._owns_client and self._client is not None:+ await self._client.aclose()+ self._client = None++ async def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:+ token = await self._token_provider()+ return {"Authorization": f"Bearer {token}", **(extra or {})}++ # -- error mapping -----------------------------------------------------++ def map_error(self, response: httpx.Response) -> StorageError:+ status = response.status_code+ reason = ""+ message = ""+ try:+ body = response.json().get("error", {})+ message = str(body.get("message", ""))+ errors = body.get("errors") or []+ if errors:+ reason = str(errors[0].get("reason", ""))+ except (ValueError, AttributeError):+ message = response.text[:200]++ if status == 401:+ return AuthRequiredError(+ f"Google Drive authentication failed: {message}",+ provider="google-drive",+ status_code=status,+ )+ if status == 404:+ return ObjectNotFoundError(+ f"Google Drive resource not found: {message}",+ provider="google-drive",+ status_code=status,+ )+ if status == 403:+ # 403 is overloaded: quota and rate limits share it with real denials.+ if reason in ("storageQuotaExceeded", "quotaExceeded"):+ return QuotaExceededError(+ f"Google Drive quota exceeded: {message}",+ provider="google-drive",+ status_code=status,+ )+ if reason in ("rateLimitExceeded", "userRateLimitExceeded"):+ return RateLimitedError(+ f"Google Drive rate limit exceeded: {message}",+ provider="google-drive",+ status_code=status,+ )+ return PermissionDeniedError(+ f"Google Drive permission denied: {message}",+ provider="google-drive",+ status_code=status,+ )+ if status == 429:+ return RateLimitedError(+ f"Google Drive rate limit exceeded: {message}",+ provider="google-drive",+ status_code=status,+ )+ return ProviderUnavailableError(+ f"Google Drive error (HTTP {status}): {message}",+ provider="google-drive",+ status_code=status,+ retryable=status >= 500,+ )++ def to_storage_object(self, resource: dict[str, Any], path: str) -> StorageObject:+ """Convert a Drive file resource into a provider-neutral StorageObject."""+ is_folder = resource.get("mimeType") == FOLDER_MIME_TYPE+ size = resource.get("size")+ properties = resource.get("appProperties") or {}++ return StorageObject(+ id=f"gdrive_{resource['id']}",+ path=path,+ name=str(resource.get("name", "")),+ provider="google-drive",+ provider_id=str(resource["id"]),+ type="folder" if is_folder else "file",+ size=int(size) if size is not None and not is_folder else None,+ mime_type=str(resource.get("mimeType")) if resource.get("mimeType") else None,+ checksum=str(resource["md5Checksum"]) if resource.get("md5Checksum") else None,+ created_at=_parse_time(resource.get("createdTime")),+ updated_at=_parse_time(resource.get("modifiedTime")),+ metadata={k: v for k, v in properties.items() if k != VIRTUAL_PATH_PROPERTY},+ )++ # -- metadata operations ----------------------------------------------++ async def list_files(self, query: str, page_size: int = 100) -> list[dict[str, Any]]:+ """Run a Drive query, following pagination."""+ results: list[dict[str, Any]] = []+ page_token: str | None = None++ while True:+ params = {+ "q": query,+ "pageSize": str(min(page_size, 1000)),+ "fields": f"nextPageToken,files({FILE_FIELDS})",+ "spaces": "drive",+ }+ if page_token:+ params["pageToken"] = page_token++ response = await self._http().get(+ f"{API_BASE}/files", params=params, headers=await self._headers()+ )+ if response.is_error:+ raise self.map_error(response)++ payload = response.json()+ results.extend(payload.get("files", []))++ page_token = payload.get("nextPageToken")+ if not page_token or len(results) >= page_size:+ break++ return results++ async def get_file(self, file_id: str) -> dict[str, Any]:+ response = await self._http().get(+ f"{API_BASE}/files/{file_id}",+ params={"fields": FILE_FIELDS},+ headers=await self._headers(),+ )+ if response.is_error:+ raise self.map_error(response)+ resource: dict[str, Any] = response.json()+ return resource++ async def create_folder(self, name: str, parent_id: str) -> str:+ body = {"name": name, "mimeType": FOLDER_MIME_TYPE, "parents": [parent_id]}+ response = await self._http().post(+ f"{API_BASE}/files",+ params={"fields": "id"},+ headers=await self._headers({"Content-Type": "application/json"}),+ content=json.dumps(body).encode("utf-8"),+ )+ if response.is_error:+ raise self.map_error(response)+ return str(response.json()["id"])++ async def delete_file(self, file_id: str) -> None:+ response = await self._http().delete(+ f"{API_BASE}/files/{file_id}", headers=await self._headers()+ )+ if response.is_error and response.status_code != 404:+ raise self.map_error(response)++ async def download_file(self, file_id: str) -> bytes:+ response = await self._http().get(+ f"{API_BASE}/files/{file_id}",+ params={"alt": "media"},+ headers=await self._headers(),+ )+ if response.is_error:+ raise self.map_error(response)+ return response.content++ async def get_quota(self) -> StorageQuota:+ response = await self._http().get(+ f"{API_BASE}/about",+ params={"fields": "storageQuota"},+ headers=await self._headers(),+ )+ if response.is_error:+ raise self.map_error(response)++ quota = response.json().get("storageQuota", {})+ used = int(quota.get("usage", 0))+ limit = quota.get("limit")+ total = int(limit) if limit is not None else None+ return StorageQuota(+ used=used, total=total, available=(total - used) if total is not None else None+ )++ # -- uploads -----------------------------------------------------------++ def build_metadata(+ self,+ *,+ name: str,+ parent_id: str,+ virtual_path: str,+ mime_type: str | None,+ extra: dict[str, str] | None = None,+ ) -> dict[str, Any]:+ """Build the file metadata, including the shared virtual-path property."""+ return {+ "name": name,+ "parents": [parent_id],+ **({"mimeType": mime_type} if mime_type else {}),+ "appProperties": {VIRTUAL_PATH_PROPERTY: virtual_path, **(extra or {})},+ }++ async def multipart_upload(+ self, metadata: dict[str, Any], payload: bytes, mime_type: str+ ) -> dict[str, Any]:+ """Upload metadata and content in a single multipart/related request."""+ boundary = "byoc-boundary-Xk3Jd9Qm2Lp7"+ body = b"".join(+ [+ f"--{boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n".encode(),+ json.dumps(metadata).encode("utf-8"),+ f"\r\n--{boundary}\r\nContent-Type: {mime_type}\r\n\r\n".encode(),+ payload,+ f"\r\n--{boundary}--".encode(),+ ]+ )++ response = await self._http().post(+ f"{UPLOAD_BASE}/files",+ params={"uploadType": "multipart", "fields": FILE_FIELDS},+ headers=await self._headers(+ {"Content-Type": f"multipart/related; boundary={boundary}"}+ ),+ content=body,+ )+ if response.is_error:+ raise self.map_error(response)+ resource: dict[str, Any] = response.json()+ return resource++ async def start_resumable_upload(self, metadata: dict[str, Any], mime_type: str) -> str:+ """Begin a resumable session and return its upload URL."""+ response = await self._http().post(+ f"{UPLOAD_BASE}/files",+ params={"uploadType": "resumable", "fields": FILE_FIELDS},+ headers=await self._headers(+ {+ "Content-Type": "application/json; charset=UTF-8",+ "X-Upload-Content-Type": mime_type,+ }+ ),+ content=json.dumps(metadata).encode("utf-8"),+ )+ if response.is_error:+ raise self.map_error(response)++ location: str | None = response.headers.get("location")+ if not location:+ raise ProviderUnavailableError(+ "Google Drive did not return a resumable upload URL.", provider="google-drive"+ )+ return str(location)++ async def upload_chunks(+ self,+ upload_url: str,+ payload: bytes,+ *,+ chunk_size: int = DEFAULT_CHUNK_SIZE,+ on_progress: Callable[[UploadProgress], None] | None = None,+ ) -> dict[str, Any]:+ """Send a payload in 256 KiB-aligned chunks to a resumable session."""+ aligned = max(CHUNK_ALIGNMENT, (chunk_size // CHUNK_ALIGNMENT) * CHUNK_ALIGNMENT)+ total = len(payload)+ offset = 0++ while offset < total:+ end = min(offset + aligned, total)+ chunk = payload[offset:end]++ response = await self._http().put(+ upload_url,+ headers={+ "Content-Length": str(len(chunk)),+ "Content-Range": f"bytes {offset}-{end - 1}/{total}",+ },+ content=chunk,+ )++ # 308 Resume Incomplete is the success signal for a non-final chunk.+ if response.status_code in (200, 201):+ if on_progress:+ on_progress(+ UploadProgress(+ bytes_uploaded=total, total_bytes=total, percentage=100.0+ )+ )+ resource: dict[str, Any] = response.json()+ return resource++ if response.status_code != 308:+ raise self.map_error(response)++ # Trust the server's committed range over our own bookkeeping.+ committed = response.headers.get("range")+ offset = int(committed.split("-")[-1]) + 1 if committed else end++ if on_progress:+ on_progress(+ UploadProgress(+ bytes_uploaded=offset,+ total_bytes=total,+ percentage=round(offset / total * 100, 2) if total else 100.0,+ )+ )++ raise ProviderUnavailableError(+ "Resumable upload ended without a completion response.", provider="google-drive"+ )++ async def stream_download(self, file_id: str) -> AsyncIterator[bytes]:+ """Stream a file's content without buffering it whole."""+ headers = await self._headers()+ async with self._http().stream(+ "GET", f"{API_BASE}/files/{file_id}", params={"alt": "media"}, headers=headers+ ) as response:+ if response.is_error:+ await response.aread()+ raise self.map_error(response)+ async for chunk in response.aiter_bytes():+ yield chunkdiff --git a/python/src/byoc/providers/gdrive/_oauth.py b/python/src/byoc/providers/gdrive/_oauth.pynew file mode 100644index 0000000..7b8d4b5--- /dev/null+++ b/python/src/byoc/providers/gdrive/_oauth.py@@ -0,0 +1,262 @@+"""Google OAuth 2.0 client with PKCE.++BYOC defaults to the ``drive.file`` scope, which grants access only to files the+app created or the user explicitly opened with it. That keeps applications out+of Google's Restricted Scope security assessment entirely.+"""++from __future__ import annotations++import time+from urllib.parse import urlencode++import httpx++from ...errors import AuthRequiredError, InvalidInputError, TokenExpiredError+from ._tokens import InMemoryTokenStorage, TokenSession, TokenStorage++AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth"+TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token"+REVOKE_ENDPOINT = "https://oauth2.googleapis.com/revoke"+++class GoogleDriveScope:+ """Scopes BYOC supports. ``FILE`` is the default and the safe choice."""++ FILE = "https://www.googleapis.com/auth/drive.file"+ APP_DATA = "https://www.googleapis.com/auth/drive.appdata"+ FILE_READONLY = "https://www.googleapis.com/auth/drive.file.readonly"+++class GoogleOAuthClient:+ """Drives the OAuth flow and keeps the access token fresh.++ Args:+ client_id: OAuth client id from the Google Cloud console.+ client_secret: Only for confidential (server-side) clients. Public+ clients use PKCE instead and must not embed a secret.+ redirect_uri: Redirect registered with the OAuth client.+ scopes: Defaults to ``[GoogleDriveScope.FILE]``.+ token_storage: Where sessions persist. Defaults to in-memory.+ session: An existing session, for pre-authenticated callers.+ client: An ``httpx.AsyncClient`` to reuse.+ """++ def __init__(+ self,+ *,+ client_id: str,+ client_secret: str | None = None,+ redirect_uri: str | None = None,+ scopes: list[str] | None = None,+ token_storage: TokenStorage | None = None,+ session: TokenSession | None = None,+ client: httpx.AsyncClient | None = None,+ ) -> None:+ if not client_id:+ raise InvalidInputError(+ "GoogleOAuthClient requires a 'client_id'.", provider="google-drive"+ )++ self.client_id = client_id+ self.client_secret = client_secret+ self.redirect_uri = redirect_uri+ self.scopes = scopes or [GoogleDriveScope.FILE]+ self.storage: TokenStorage = token_storage or InMemoryTokenStorage()++ if session is not None:+ self.storage.set(session)++ self._client = client+ self._owns_client = client is None++ def _http(self) -> httpx.AsyncClient:+ if self._client is None:+ self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0))+ self._owns_client = True+ return self._client++ async def aclose(self) -> None:+ if self._owns_client and self._client is not None:+ await self._client.aclose()+ self._client = None++ # -- authorization -----------------------------------------------------++ def get_authorization_url(+ self,+ *,+ state: str | None = None,+ code_challenge: str | None = None,+ code_challenge_method: str = "S256",+ redirect_uri: str | None = None,+ prompt: str = "consent",+ access_type: str = "offline",+ scopes: list[str] | None = None,+ ) -> str:+ """Build the URL to send the user to for consent.++ ``access_type="offline"`` with ``prompt="consent"`` is what makes Google+ return a refresh token; without both, the session dies in an hour and+ cannot be renewed.+ """+ target_redirect = redirect_uri or self.redirect_uri+ if not target_redirect:+ raise InvalidInputError(+ "A 'redirect_uri' is required to build the authorization URL.",+ provider="google-drive",+ )++ params = {+ "client_id": self.client_id,+ "redirect_uri": target_redirect,+ "response_type": "code",+ "scope": " ".join(scopes or self.scopes),+ "access_type": access_type,+ "prompt": prompt,+ "include_granted_scopes": "true",+ }+ if state:+ params["state"] = state+ if code_challenge:+ params["code_challenge"] = code_challenge+ params["code_challenge_method"] = code_challenge_method++ return f"{AUTH_ENDPOINT}?{urlencode(params)}"++ async def exchange_code(+ self, *, code: str, code_verifier: str | None = None, redirect_uri: str | None = None+ ) -> TokenSession:+ """Exchange an authorization code for a session, and store it."""+ target_redirect = redirect_uri or self.redirect_uri+ if not target_redirect:+ raise InvalidInputError(+ "A 'redirect_uri' is required to exchange an authorization code.",+ provider="google-drive",+ )++ form = {+ "client_id": self.client_id,+ "code": code,+ "grant_type": "authorization_code",+ "redirect_uri": target_redirect,+ }+ if self.client_secret:+ form["client_secret"] = self.client_secret+ if code_verifier:+ form["code_verifier"] = code_verifier++ payload = await self._post_token(form, "Authorization code exchange failed")+ session = self._session_from_payload(payload, existing_refresh_token=None)+ self.storage.set(session)+ return session++ async def refresh_access_token(self, refresh_token: str | None = None) -> TokenSession:+ """Mint a fresh access token from the stored refresh token."""+ stored = self.storage.get()+ token = refresh_token or (stored.refresh_token if stored else None)++ if not token:+ raise AuthRequiredError(+ "No refresh token available; the user must authorize again.",+ provider="google-drive",+ )++ form = {+ "client_id": self.client_id,+ "refresh_token": token,+ "grant_type": "refresh_token",+ }+ if self.client_secret:+ form["client_secret"] = self.client_secret++ payload = await self._post_token(form, "Token refresh failed")+ # Google omits refresh_token on refresh responses; keep the existing one.+ session = self._session_from_payload(payload, existing_refresh_token=token)+ self.storage.set(session)+ return session++ async def get_access_token(self) -> str:+ """Return a valid access token, refreshing it if needed."""+ session = self.storage.get()+ if session is None:+ raise AuthRequiredError(+ "No Google Drive session. Complete the OAuth flow first.",+ provider="google-drive",+ )+ if not session.is_expired:+ return session.access_token++ refreshed = await self.refresh_access_token()+ return refreshed.access_token++ async def has_valid_session(self) -> bool:+ """Whether a usable session exists, without raising."""+ session = self.storage.get()+ if session is None:+ return False+ if not session.is_expired:+ return True+ return session.refresh_token is not None++ async def set_session(self, session: TokenSession) -> None:+ self.storage.set(session)++ async def revoke(self) -> None:+ """Revoke the token with Google and clear local storage.++ Storage is cleared even if the remote call fails, so a revoked or+ already-invalid token cannot linger on disk.+ """+ session = self.storage.get()+ token = (session.refresh_token or session.access_token) if session else None+ try:+ if token:+ await self._http().post(REVOKE_ENDPOINT, data={"token": token})+ finally:+ self.storage.clear()++ # -- internals ---------------------------------------------------------++ async def _post_token(self, form: dict[str, str], failure_message: str) -> dict[str, object]:+ response = await self._http().post(TOKEN_ENDPOINT, data=form)+ if response.is_error:+ detail = ""+ try:+ body = response.json()+ detail = f"{body.get('error', '')}: {body.get('error_description', '')}".strip(": ")+ except ValueError:+ detail = response.text[:200]++ # invalid_grant means the refresh token is dead: re-consent required.+ if response.status_code in (400, 401) and "invalid_grant" in detail:+ raise TokenExpiredError(+ f"{failure_message} (invalid_grant): the user must authorize again.",+ provider="google-drive",+ status_code=response.status_code,+ )+ raise AuthRequiredError(+ f"{failure_message} (HTTP {response.status_code}): {detail}",+ provider="google-drive",+ status_code=response.status_code,+ )++ payload: dict[str, object] = response.json()+ return payload++ @staticmethod+ def _session_from_payload(+ payload: dict[str, object], *, existing_refresh_token: str | None+ ) -> TokenSession:+ expires_in = payload.get("expires_in")+ expires_at = time.time() + float(expires_in) if expires_in is not None else None # type: ignore[arg-type]++ return TokenSession(+ access_token=str(payload["access_token"]),+ refresh_token=str(payload["refresh_token"])+ if payload.get("refresh_token")+ else existing_refresh_token,+ expires_at=expires_at,+ token_type=str(payload.get("token_type") or "Bearer"),+ scope=str(payload["scope"]) if payload.get("scope") else None,+ )diff --git a/python/src/byoc/providers/gdrive/_pkce.py b/python/src/byoc/providers/gdrive/_pkce.pynew file mode 100644index 0000000..746555e--- /dev/null+++ b/python/src/byoc/providers/gdrive/_pkce.py@@ -0,0 +1,57 @@+"""PKCE (RFC 7636) helpers for the Google Drive OAuth flow.++PKCE is what stops an intercepted authorization code from being redeemed by an+attacker, so the verifier must come from a cryptographically secure RNG -- never+``random``. Behaviour is pinned by ``spec/fixtures/pkce.json``, whose first+vector is RFC 7636 Appendix B.+"""++from __future__ import annotations++import base64+import hashlib+import secrets++from ...errors import InvalidInputError++MIN_VERIFIER_LENGTH = 43+MAX_VERIFIER_LENGTH = 128++# RFC 7636 section 4.1: verifiers use the unreserved character set.+_VERIFIER_ALPHABET = (+ "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"+)+++def _base64url(raw: bytes) -> str:+ """Base64url-encode without padding, per RFC 7636."""+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")+++def generate_code_verifier(length: int = 64) -> str:+ """Generate a cryptographically random ``code_verifier``.++ Args:+ length: Desired length, clamped to the RFC's 43..128 range.+ """+ size = max(MIN_VERIFIER_LENGTH, min(MAX_VERIFIER_LENGTH, length))+ return "".join(secrets.choice(_VERIFIER_ALPHABET) for _ in range(size))+++def generate_code_challenge(verifier: str) -> str:+ """Derive the S256 ``code_challenge`` from a verifier.++ The challenge is the base64url-encoded SHA-256 of the ASCII verifier.+ """+ if not verifier:+ raise InvalidInputError("PKCE code_verifier must not be empty.", provider="google-drive")+ return _base64url(hashlib.sha256(verifier.encode("ascii")).digest())+++def generate_oauth_state(length: int = 32) -> str:+ """Generate a random ``state`` value for CSRF protection.++ The caller must store this and compare it against the value returned on the+ redirect; skipping that check leaves the flow open to CSRF.+ """+ return secrets.token_urlsafe(max(16, length))[:length]diff --git a/python/src/byoc/providers/gdrive/_resolver.py b/python/src/byoc/providers/gdrive/_resolver.pynew file mode 100644index 0000000..74f651c--- /dev/null+++ b/python/src/byoc/providers/gdrive/_resolver.py@@ -0,0 +1,239 @@+"""Virtual path <-> Drive file ID resolution.++Google Drive addresses files by opaque IDs, not paths, so every operation on+``users/123/report.pdf`` costs a chain of lookups. This module caches those+lookups and self-heals when a user renames or deletes something in the Drive web+UI behind our back.+"""++from __future__ import annotations++import time+from dataclasses import dataclass+from typing import Any, Protocol++from ...errors import ObjectNotFoundError+from ...paths import get_basename, get_dirname, normalize_virtual_path, split_path++FOLDER_MIME_TYPE = "application/vnd.google-apps.folder"++# The metadata key BYOC writes into Drive's appProperties.+#+# This is WIRE FORMAT shared with every other BYOC SDK -- see+# spec/fixtures/provider-metadata.json. It stays camelCase in Python on purpose:+# renaming it would make files written here invisible to the TypeScript SDK.+VIRTUAL_PATH_PROPERTY = "byocVirtualPath"++DEFAULT_CACHE_TTL_SECONDS = 300.0+DEFAULT_CACHE_MAX_ENTRIES = 1000+++def escape_drive_query_value(value: str) -> str:+ """Escape a value for a Drive API v3 query string literal.++ Drive requires ``\\`` and ``'`` to be backslash-escaped. Without this, a file+ named ``Bob's Notes.pdf`` produces a malformed query -- and a crafted name+ could inject query clauses and match files it should not.++ The order matters: backslashes first, or the escapes added for quotes get+ escaped a second time.+ """+ return value.replace("\\", "\\\\").replace("'", "\\'")+++@dataclass(slots=True)+class _CacheEntry:+ file_id: str+ expires_at: float+++class LruTtlPathCache:+ """Small LRU cache with a TTL, mapping virtual paths to Drive file IDs.++ The TTL bounds how long a stale mapping can survive an out-of-band change;+ the LRU bound stops a long-lived process from growing without limit.+ """++ def __init__(+ self,+ *,+ ttl_seconds: float = DEFAULT_CACHE_TTL_SECONDS,+ max_entries: int = DEFAULT_CACHE_MAX_ENTRIES,+ ) -> None:+ self._ttl = ttl_seconds+ self._max_entries = max_entries+ self._entries: dict[str, _CacheEntry] = {}++ def get(self, path: str) -> str | None:+ entry = self._entries.get(path)+ if entry is None:+ return None+ if time.monotonic() >= entry.expires_at:+ del self._entries[path]+ return None+ # Refresh recency for the LRU ordering.+ self._entries[path] = self._entries.pop(path)+ return entry.file_id++ def set(self, path: str, file_id: str) -> None:+ if path in self._entries:+ del self._entries[path]+ elif len(self._entries) >= self._max_entries:+ oldest = next(iter(self._entries))+ del self._entries[oldest]+ self._entries[path] = _CacheEntry(+ file_id=file_id, expires_at=time.monotonic() + self._ttl+ )++ def invalidate(self, path: str) -> None:+ """Drop a path and everything beneath it.++ Descendants go too: if ``a/b`` moved, every cached ``a/b/...`` id is+ suspect even though the ids themselves may still be valid.+ """+ self._entries.pop(path, None)+ prefix = f"{path}/"+ for key in [k for k in self._entries if k.startswith(prefix)]:+ del self._entries[key]++ def clear(self) -> None:+ self._entries.clear()++ def __len__(self) -> int:+ return len(self._entries)+++class DrivePathResolver:+ """Resolves virtual paths to Drive file IDs, creating folders on demand.++ Args:+ http: The Drive HTTP client used for lookups.+ root_folder_name: Application folder created at the Drive root.+ cache: Optional cache override.+ """++ def __init__(+ self,+ http: DriveHttpProtocol,+ *,+ root_folder_name: str = "BYOC",+ cache: LruTtlPathCache | None = None,+ ) -> None:+ self._http = http+ self._root_folder_name = root_folder_name+ self._cache = cache or LruTtlPathCache()+ self._root_id: str | None = None++ @property+ def cache(self) -> LruTtlPathCache:+ return self._cache++ def invalidate(self, path: str) -> None:+ """Forget a cached mapping, e.g. after a 404 or a move."""+ self._cache.invalidate(normalize_virtual_path(path))++ async def ensure_root_folder(self) -> str:+ """Return the app root folder id, creating it if absent."""+ if self._root_id is not None:+ return self._root_id++ escaped = escape_drive_query_value(self._root_folder_name)+ query = (+ f"name = '{escaped}' and 'root' in parents "+ f"and mimeType = '{FOLDER_MIME_TYPE}' and trashed = false"+ )+ found = await self._http.list_files(query, page_size=1)+ if found:+ self._root_id = str(found[0]["id"])+ else:+ self._root_id = await self._http.create_folder(self._root_folder_name, "root")+ return self._root_id++ async def resolve_folder_id(self, path: str, *, create: bool = False) -> str:+ """Resolve a folder path to its Drive id.++ Args:+ create: Create missing folders instead of raising.+ """+ normalized = normalize_virtual_path(path)+ if not normalized:+ return await self.ensure_root_folder()++ cached = self._cache.get(normalized)+ if cached is not None:+ return cached++ parent_id = await self.ensure_root_folder()+ walked = ""++ for segment in split_path(normalized):+ walked = f"{walked}/{segment}" if walked else segment++ cached_segment = self._cache.get(walked)+ if cached_segment is not None:+ parent_id = cached_segment+ continue++ escaped = escape_drive_query_value(segment)+ query = (+ f"name = '{escaped}' and '{parent_id}' in parents "+ f"and mimeType = '{FOLDER_MIME_TYPE}' and trashed = false"+ )+ matches = await self._http.list_files(query, page_size=1)++ if matches:+ parent_id = str(matches[0]["id"])+ elif create:+ parent_id = await self._http.create_folder(segment, parent_id)+ else:+ raise ObjectNotFoundError(+ f"Folder not found in Google Drive: {walked}", provider="google-drive"+ )++ self._cache.set(walked, parent_id)++ return parent_id++ async def resolve_parent_folder_id(self, path: str, *, create: bool = True) -> str:+ """Resolve the parent folder of a file path."""+ return await self.resolve_folder_id(get_dirname(path), create=create)++ async def resolve_file_id(self, path: str) -> str:+ """Resolve a file path to its Drive id.++ Raises:+ ObjectNotFoundError: if no matching untrashed file exists.+ """+ normalized = normalize_virtual_path(path)+ if not normalized:+ return await self.ensure_root_folder()++ cached = self._cache.get(normalized)+ if cached is not None:+ return cached++ parent_id = await self.resolve_folder_id(get_dirname(normalized), create=False)+ filename = get_basename(normalized)+ escaped = escape_drive_query_value(filename)+ query = f"name = '{escaped}' and '{parent_id}' in parents and trashed = false"++ matches = await self._http.list_files(query, page_size=10)+ if not matches:+ raise ObjectNotFoundError(+ f"File not found in Google Drive: {normalized}", provider="google-drive"+ )++ file_id = str(matches[0]["id"])+ self._cache.set(normalized, file_id)+ return file_id+++class DriveHttpProtocol(Protocol):+ """The subset of the Drive HTTP client the resolver needs.++ A structural protocol, so the resolver can be exercised without HTTP.+ """++ async def list_files(self, query: str, page_size: int = 100) -> list[dict[str, Any]]: ...++ async def create_folder(self, name: str, parent_id: str) -> str: ...diff --git a/python/src/byoc/providers/gdrive/_tokens.py b/python/src/byoc/providers/gdrive/_tokens.pynew file mode 100644index 0000000..afe50ab--- /dev/null+++ b/python/src/byoc/providers/gdrive/_tokens.py@@ -0,0 +1,125 @@+"""OAuth session types and token storage backends."""++from __future__ import annotations++import json+import os+import time+from dataclasses import dataclass, replace+from pathlib import Path+from typing import Protocol++from ...encryption import E2EECrypto+from ...errors import StorageError++# Refresh slightly early so a token cannot expire between the check and the call.+EXPIRY_SKEW_SECONDS = 60+++@dataclass(frozen=True, slots=True)+class TokenSession:+ """An OAuth session. ``refresh_token`` is the long-lived secret."""++ access_token: str+ refresh_token: str | None = None+ expires_at: float | None = None+ token_type: str = "Bearer"+ scope: str | None = None++ @property+ def is_expired(self) -> bool:+ """Whether the access token is expired or about to be."""+ if self.expires_at is None:+ return False+ return time.time() >= self.expires_at - EXPIRY_SKEW_SECONDS++ def to_dict(self) -> dict[str, object]:+ return {+ "access_token": self.access_token,+ "refresh_token": self.refresh_token,+ "expires_at": self.expires_at,+ "token_type": self.token_type,+ "scope": self.scope,+ }++ @classmethod+ def from_dict(cls, raw: dict[str, object]) -> TokenSession:+ return cls(+ access_token=str(raw["access_token"]),+ refresh_token=str(raw["refresh_token"]) if raw.get("refresh_token") else None,+ expires_at=float(raw["expires_at"]) if raw.get("expires_at") else None, # type: ignore[arg-type]+ token_type=str(raw.get("token_type") or "Bearer"),+ scope=str(raw["scope"]) if raw.get("scope") else None,+ )++ def with_access_token(self, access_token: str, expires_at: float | None) -> TokenSession:+ return replace(self, access_token=access_token, expires_at=expires_at)+++class TokenStorage(Protocol):+ """Where refresh tokens live between calls."""++ def get(self) -> TokenSession | None: ...+ def set(self, session: TokenSession) -> None: ...+ def clear(self) -> None: ...+++class InMemoryTokenStorage:+ """Default storage. Sessions are lost on restart, so the user re-consents.++ Fine for scripts and tests; use :class:`EncryptedFileTokenStorage` for a+ long-running service.+ """++ def __init__(self, session: TokenSession | None = None) -> None:+ self._session = session++ def get(self) -> TokenSession | None:+ return self._session++ def set(self, session: TokenSession) -> None:+ self._session = session++ def clear(self) -> None:+ self._session = None+++class EncryptedFileTokenStorage:+ """Persists a session to disk, encrypted with AES-256-GCM.++ A refresh token grants long-lived access to the user's Drive, so it is never+ written in plaintext. The file is also created with owner-only permissions.++ Args:+ file_path: Where to store the encrypted session.+ encryption_key: Passphrase used to derive the encryption key.+ """++ def __init__(self, file_path: str | Path, encryption_key: str) -> None:+ self._path = Path(file_path)+ self._crypto = E2EECrypto(passphrase=encryption_key)++ def get(self) -> TokenSession | None:+ if not self._path.exists():+ return None+ try:+ payload = self._crypto.decrypt_sync(self._path.read_bytes())+ except StorageError:+ # A corrupt file, or one written under a different encryption key,+ # is unreadable either way. Both mean the same thing to the caller:+ # there is no usable session, so re-authenticate.+ return None+ raw: dict[str, object] = json.loads(payload.decode("utf-8"))+ return TokenSession.from_dict(raw)++ def set(self, session: TokenSession) -> None:+ envelope = self._crypto.encrypt_sync(json.dumps(session.to_dict()).encode("utf-8"))+ self._path.parent.mkdir(parents=True, exist_ok=True)+ # Create with 0600 before writing, so the token is never briefly+ # world-readable on a shared machine.+ descriptor = os.open(self._path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)+ with os.fdopen(descriptor, "wb") as handle:+ handle.write(envelope)++ def clear(self) -> None:+ self._path.unlink(missing_ok=True)diff --git a/python/src/byoc/providers/gdrive/adapter.py b/python/src/byoc/providers/gdrive/adapter.pynew file mode 100644index 0000000..c6fa19a--- /dev/null+++ b/python/src/byoc/providers/gdrive/adapter.py@@ -0,0 +1,256 @@+"""Google Drive provider adapter."""++from __future__ import annotations++from collections.abc import AsyncIterator, Awaitable, Callable+from typing import TypeVar++import httpx++from ...errors import InvalidInputError, ObjectNotFoundError+from ...paths import get_basename, normalize_virtual_path+from ...types import (+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+)+from ._http import RESUMABLE_THRESHOLD, DriveHttpClient+from ._oauth import GoogleDriveScope, GoogleOAuthClient+from ._resolver import DrivePathResolver, LruTtlPathCache+from ._tokens import TokenSession, TokenStorage++PROVIDER_ID = "google-drive"++T = TypeVar("T")+++class GoogleDriveProvider:+ """Store application files in the Drive account your user already owns.++ Uses the ``drive.file`` scope by default, so the app can only see files it+ created or that the user explicitly opened with it -- which keeps you out of+ Google's Restricted Scope security assessment.++ Args:+ client_id: OAuth client id.+ client_secret: Only for confidential server-side clients.+ redirect_uri: Redirect registered with the OAuth client.+ scopes: Defaults to ``[GoogleDriveScope.FILE]``.+ token_storage: Where the session persists between runs.+ session: An existing session, for pre-authenticated callers.+ root_folder_name: App folder created at the Drive root.+ cache: Optional path-cache override.+ client: An ``httpx.AsyncClient`` to reuse.+ """++ def __init__(+ self,+ *,+ client_id: str,+ client_secret: str | None = None,+ redirect_uri: str | None = None,+ scopes: list[str] | None = None,+ token_storage: TokenStorage | None = None,+ session: TokenSession | None = None,+ root_folder_name: str = "BYOC",+ cache: LruTtlPathCache | None = None,+ client: httpx.AsyncClient | None = None,+ ) -> None:+ if not client_id:+ raise InvalidInputError(+ "GoogleDriveProvider requires a 'client_id'.", provider=PROVIDER_ID+ )++ self.oauth = GoogleOAuthClient(+ client_id=client_id,+ client_secret=client_secret,+ redirect_uri=redirect_uri,+ scopes=scopes or [GoogleDriveScope.FILE],+ token_storage=token_storage,+ session=session,+ client=client,+ )+ self.http = DriveHttpClient(self.oauth.get_access_token, client=client)+ self.resolver = DrivePathResolver(+ self.http, root_folder_name=root_folder_name, cache=cache+ )+ self.root_folder_name = root_folder_name++ # -- lifecycle ---------------------------------------------------------++ def manifest(self) -> ProviderManifest:+ return ProviderManifest(+ id=PROVIDER_ID,+ name="Google Drive",+ category="personal-cloud",+ authentication="oauth2",+ supports_user_owned_storage=True,+ adapter_version="0.2.0",+ )++ def capabilities(self) -> ProviderCapabilities:+ return ProviderCapabilities(+ folders=True,+ sharing=True,+ public_urls=False,+ resumable_uploads=True,+ versioning=True,+ quota=True,+ server_side_copy=True,+ )++ async def connect(self) -> None:+ """Verify the session and ensure the app root folder exists."""+ await self.resolver.ensure_root_folder()++ async def disconnect(self) -> None:+ """Close HTTP resources. Does not revoke the token -- use ``oauth.revoke()``."""+ await self.http.aclose()+ await self.oauth.aclose()++ # -- operations --------------------------------------------------------++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ normalized = normalize_virtual_path(path)+ if not normalized:+ raise InvalidInputError("Upload requires a file path.", provider=PROVIDER_ID)++ if isinstance(data, str):+ payload = data.encode("utf-8")+ elif isinstance(data, bytes | bytearray | memoryview):+ payload = bytes(data)+ else:+ raise InvalidInputError(+ "Google Drive upload requires bytes or str.", provider=PROVIDER_ID+ )++ mime = (options.mime_type if options else None) or "application/octet-stream"+ parent_id = await self.resolver.resolve_parent_folder_id(normalized, create=True)++ metadata = self.http.build_metadata(+ name=get_basename(normalized),+ parent_id=parent_id,+ virtual_path=normalized,+ mime_type=mime,+ extra=dict(options.metadata) if options else None,+ )++ resumable = options.resumable if options and options.resumable is not None else None+ wants_resumable = (+ resumable+ if resumable is not None+ else (len(payload) > RESUMABLE_THRESHOLD or bool(options and options.on_progress))+ )++ if wants_resumable:+ upload_url = await self.http.start_resumable_upload(metadata, mime)+ resource = await self.http.upload_chunks(+ upload_url,+ payload,+ chunk_size=(+ options.chunk_size if options and options.chunk_size else 8 * 1024 * 1024+ ),+ on_progress=options.on_progress if options else None,+ )+ else:+ resource = await self.http.multipart_upload(metadata, payload, mime)++ obj = self.http.to_storage_object(resource, normalized)+ self.resolver.cache.set(normalized, obj.provider_id)+ return obj++ async def download(self, path: str) -> StorageOutput:+ normalized = normalize_virtual_path(path)++ async def fetch(file_id: str) -> tuple[dict[str, object], bytes]:+ return await self.http.get_file(file_id), await self.http.download_file(file_id)++ resource, body = await self._with_healing(normalized, fetch)++ async def stream() -> AsyncIterator[bytes]:+ yield body++ async def read() -> bytes:+ return body++ return StorageOutput(+ metadata=self.http.to_storage_object(resource, normalized), stream=stream, read=read+ )++ async def delete(self, path: str) -> None:+ normalized = normalize_virtual_path(path)+ try:+ await self._with_healing(normalized, self.http.delete_file)+ except ObjectNotFoundError:+ return # Already gone: deletion is idempotent.+ finally:+ self.resolver.invalidate(normalized)++ async def metadata(self, path: str) -> StorageObject:+ normalized = normalize_virtual_path(path)+ resource = await self._with_healing(normalized, self.http.get_file)+ return self.http.to_storage_object(resource, normalized)++ async def exists(self, path: str) -> bool:+ try:+ await self.metadata(path)+ except ObjectNotFoundError:+ return False+ return True++ async def list(self, path: str | None = None) -> list[StorageObject]:+ normalized = normalize_virtual_path(path)+ parent_id = await self.resolver.resolve_folder_id(normalized, create=False)++ query = f"'{parent_id}' in parents and trashed = false"+ resources = await self.http.list_files(query, page_size=1000)++ results: list[StorageObject] = []+ for resource in resources:+ name = str(resource.get("name", ""))+ child_path = f"{normalized}/{name}" if normalized else name+ results.append(self.http.to_storage_object(resource, child_path))+ return results++ async def create_folder(self, path: str) -> StorageObject:+ normalized = normalize_virtual_path(path)+ if not normalized:+ raise InvalidInputError("Create folder requires a path.", provider=PROVIDER_ID)++ folder_id = await self.resolver.resolve_folder_id(normalized, create=True)+ return StorageObject(+ id=f"gdrive_{folder_id}",+ path=normalized,+ name=get_basename(normalized),+ provider=PROVIDER_ID,+ provider_id=folder_id,+ type="folder",+ )++ async def quota(self) -> StorageQuota:+ return await self.http.get_quota()++ # -- internals ---------------------------------------------------------++ async def _with_healing(+ self, normalized: str, operation: Callable[[str], Awaitable[T]]+ ) -> T:+ """Resolve a path and run ``operation`` on it, healing a stale cache.++ Users rename and delete files in the Drive web UI, so a cached id can go+ bad in two different ways: the path stops resolving, or it resolves to+ an id Drive has already deleted. Only the first is caught by retrying+ resolution alone, which is why the operation itself is inside the retry.+ A second failure is genuine and propagates.+ """+ try:+ return await operation(await self.resolver.resolve_file_id(normalized))+ except ObjectNotFoundError:+ self.resolver.invalidate(normalized)+ return await operation(await self.resolver.resolve_file_id(normalized))diff --git a/python/src/byoc/providers/s3.py b/python/src/byoc/providers/s3.pynew file mode 100644index 0000000..d876708--- /dev/null+++ b/python/src/byoc/providers/s3.py@@ -0,0 +1,429 @@+"""S3-compatible provider adapter.++Works against AWS S3, Cloudflare R2, MinIO, Wasabi, and any endpoint speaking+the S3 API. Bucket names, object keys, ETags and multipart uploads stay private+to this module -- BYOC core never sees them.+"""++from __future__ import annotations++from collections.abc import AsyncIterator+from datetime import datetime+from email.utils import parsedate_to_datetime+from typing import Any+from xml.etree import ElementTree++import httpx++from ..errors import (+ InvalidInputError,+ ObjectNotFoundError,+ PermissionDeniedError,+ ProviderUnavailableError,+ RateLimitedError,+ StorageError,+)+from ..paths import encode_path_segments, get_basename, normalize_virtual_path+from ..retry import with_retry+from ..types import (+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ UploadOptions,+)+from ._sigv4 import create_presigned_s3_url, sign_s3_request++PROVIDER_ID = "s3-compatible"+_S3_NS = "{http://s3.amazonaws.com/doc/2006-03-01/}"+_LIST_PAGE_GUARD = 10_000 # pages, not keys: stops a malformed server looping forever+++def _text(element: Any, tag: str) -> str | None:+ """Read a child tag, tolerating servers that omit the S3 XML namespace."""+ found = element.find(f"{_S3_NS}{tag}")+ if found is None:+ found = element.find(tag)+ return found.text if found is not None else None+++class S3CompatibleProvider:+ """Storage adapter for S3-compatible object stores.++ Args:+ endpoint: Base endpoint, e.g. ``https://<account>.r2.cloudflarestorage.com``.+ bucket: Bucket name.+ region: Region, or ``"auto"`` for Cloudflare R2.+ access_key_id: Access key.+ secret_access_key: Secret key.+ root_prefix: Optional key prefix all paths are stored under.+ force_path_style: Put the bucket in the URL path rather than the+ hostname. Required by MinIO and most self-hosted gateways.+ client: An existing ``httpx.AsyncClient`` to reuse. If omitted, one is+ created and closed by :meth:`disconnect`.+ """++ def __init__(+ self,+ *,+ endpoint: str,+ bucket: str,+ region: str,+ access_key_id: str,+ secret_access_key: str,+ root_prefix: str | None = None,+ force_path_style: bool = False,+ client: httpx.AsyncClient | None = None,+ ) -> None:+ if not endpoint or not bucket or not access_key_id or not secret_access_key:+ raise InvalidInputError(+ "S3CompatibleProvider requires endpoint, bucket, access_key_id, "+ "and secret_access_key.",+ provider=PROVIDER_ID,+ )++ self.endpoint = endpoint.rstrip("/")+ self.bucket = bucket+ self.region = region+ self.access_key_id = access_key_id+ self.secret_access_key = secret_access_key+ self.root_prefix = normalize_virtual_path(root_prefix) if root_prefix else ""+ self.force_path_style = force_path_style++ self._client = client+ self._owns_client = client is None++ # -- lifecycle ---------------------------------------------------------++ def manifest(self) -> ProviderManifest:+ return ProviderManifest(+ id=PROVIDER_ID,+ name="S3 Compatible (R2/AWS/MinIO)",+ category="developer-cloud",+ authentication="access-key",+ supports_user_owned_storage=False,+ adapter_version="0.2.0",+ )++ def capabilities(self) -> ProviderCapabilities:+ # S3 has no native folders and reports no account quota, so those stay+ # False rather than being faked with prefix tricks.+ return ProviderCapabilities(+ folders=False,+ sharing=False,+ public_urls=True,+ resumable_uploads=True,+ versioning=True,+ quota=False,+ server_side_copy=True,+ )++ async def connect(self) -> None:+ """No-op: SigV4 is stateless. Ensures an HTTP client exists."""+ self._http()++ async def disconnect(self) -> None:+ """Close the HTTP client if this adapter created it."""+ if self._owns_client and self._client is not None:+ await self._client.aclose()+ self._client = None++ def _http(self) -> httpx.AsyncClient:+ if self._client is None:+ self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0, read=300.0))+ self._owns_client = True+ return self._client++ # -- key handling ------------------------------------------------------++ def _to_key(self, path: str) -> str:+ """Virtual path -> provider-side object key (adds ``root_prefix``)."""+ normalized = normalize_virtual_path(path)+ return f"{self.root_prefix}/{normalized}" if self.root_prefix else normalized++ def _to_virtual_path(self, key: str) -> str:+ """Provider-side object key -> virtual path (strips ``root_prefix``).++ ``root_prefix`` is the adapter's business, so it must not appear in a+ returned ``StorageObject.path``: callers feed those paths straight back+ into the client, and a leaked prefix would be applied a second time.+ The full key stays available as ``provider_id``.+ """+ if self.root_prefix and key.startswith(f"{self.root_prefix}/"):+ return key[len(self.root_prefix) + 1 :]+ return key++ def _bucket_base_url(self) -> str:+ return f"{self.endpoint}/{self.bucket}" if self.force_path_style else self.endpoint++ def object_url(self, key: str) -> str:+ """Absolute URL for an object key, with each segment RFC 3986 encoded.++ Segment-wise encoding is what keeps ``#`` and ``?`` in filenames from+ truncating the key into a fragment or query string.+ """+ return f"{self._bucket_base_url()}/{encode_path_segments(key)}"++ def presigned_url(+ self, path: str, *, method: str = "GET", expires_in_seconds: int = 3600+ ) -> str:+ """Time-limited URL a browser can use directly, without proxying bytes."""+ return create_presigned_s3_url(+ access_key_id=self.access_key_id,+ secret_access_key=self.secret_access_key,+ region=self.region,+ url=self.object_url(self._to_key(path)),+ method=method,+ expires_in_seconds=expires_in_seconds,+ )++ def _sign(+ self,+ method: str,+ url: str,+ headers: dict[str, str] | None = None,+ body: bytes | None = None,+ ) -> dict[str, str]:+ return sign_s3_request(+ access_key_id=self.access_key_id,+ secret_access_key=self.secret_access_key,+ region=self.region,+ method=method,+ url=url,+ headers=headers,+ body=body,+ )++ # -- error mapping -----------------------------------------------------++ def _map_error(self, response: httpx.Response, body: str = "") -> StorageError:+ status = response.status_code++ if status == 404 or "NoSuchKey" in body or "NoSuchBucket" in body:+ return ObjectNotFoundError(+ f"S3 object not found (HTTP {status}).",+ provider=PROVIDER_ID,+ status_code=status,+ )+ if status in (401, 403) or "AccessDenied" in body:+ return PermissionDeniedError(+ "S3 access denied: invalid credentials or insufficient permissions.",+ provider=PROVIDER_ID,+ status_code=status,+ )+ if status == 429 or "SlowDown" in body:+ return RateLimitedError(+ "S3 rate limit exceeded.", provider=PROVIDER_ID, status_code=status+ )+ return ProviderUnavailableError(+ f"S3 error (HTTP {status}): {body[:300]}",+ provider=PROVIDER_ID,+ status_code=status,+ retryable=status >= 500,+ )++ def _object_from_headers(self, key: str, response: httpx.Response) -> StorageObject:+ etag = response.headers.get("etag", "").strip('"') or None+ length = response.headers.get("content-length")+ last_modified = response.headers.get("last-modified")++ updated_at: datetime | None = None+ if last_modified:+ try:+ updated_at = parsedate_to_datetime(last_modified)+ except (TypeError, ValueError):+ updated_at = None++ virtual = self._to_virtual_path(key)+ return StorageObject(+ id=f"s3_{self.bucket}_{key}",+ path=virtual,+ name=get_basename(virtual),+ provider=PROVIDER_ID,+ provider_id=key,+ type="file",+ size=int(length) if length is not None else None,+ mime_type=response.headers.get("content-type"),+ checksum=etag,+ updated_at=updated_at,+ )++ # -- operations --------------------------------------------------------++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ key = self._to_key(path)+ url = self.object_url(key)++ if isinstance(data, str):+ payload = data.encode("utf-8")+ elif isinstance(data, bytes | bytearray | memoryview):+ payload = bytes(data)+ else:+ raise InvalidInputError(+ "S3 upload requires bytes or str. Streaming uploads are not yet supported.",+ provider=PROVIDER_ID,+ )++ mime = (options.mime_type if options else None) or "application/octet-stream"+ headers = {"content-type": mime}+ for meta_key, meta_value in (options.metadata if options else {}).items():+ headers[f"x-amz-meta-{meta_key.lower()}"] = meta_value++ async def send() -> StorageObject:+ signed = self._sign("PUT", url, headers, payload)+ response = await self._http().put(url, headers=signed, content=payload)+ if response.is_error:+ raise self._map_error(response, response.text)++ etag = response.headers.get("etag", "").strip('"') or None+ virtual = self._to_virtual_path(key)+ return StorageObject(+ id=f"s3_{self.bucket}_{key}",+ path=virtual,+ name=get_basename(virtual),+ provider=PROVIDER_ID,+ provider_id=key,+ type="file",+ size=len(payload),+ mime_type=mime,+ checksum=etag,+ metadata=dict(options.metadata) if options else {},+ )++ return await with_retry(send)++ async def download(self, path: str) -> StorageOutput:+ key = self._to_key(path)+ url = self.object_url(key)++ async def fetch() -> httpx.Response:+ response = await self._http().get(url, headers=self._sign("GET", url))+ if response.is_error:+ raise self._map_error(response, response.text)+ return response++ response = await with_retry(fetch)+ body = response.content++ async def stream() -> AsyncIterator[bytes]:+ yield body++ async def read() -> bytes:+ return body++ return StorageOutput(+ metadata=self._object_from_headers(key, response), stream=stream, read=read+ )++ async def delete(self, path: str) -> None:+ key = self._to_key(path)+ url = self.object_url(key)++ async def send() -> None:+ signed = self._sign("DELETE", url)+ response = await self._http().request("DELETE", url, headers=signed)+ # S3 delete is idempotent: a missing object is a successful delete.+ if response.is_error and response.status_code != 404:+ raise self._map_error(response, response.text)++ await with_retry(send)++ async def metadata(self, path: str) -> StorageObject:+ key = self._to_key(path)+ url = self.object_url(key)++ async def send() -> StorageObject:+ response = await self._http().head(url, headers=self._sign("HEAD", url))+ if response.is_error:+ raise self._map_error(response)+ return self._object_from_headers(key, response)++ return await with_retry(send)++ async def exists(self, path: str) -> bool:+ try:+ await self.metadata(path)+ except ObjectNotFoundError:+ return False+ return True++ async def list(self, path: str | None = None) -> list[StorageObject]:+ """List objects directly under ``path`` using ListObjectsV2.++ Follows ``NextContinuationToken`` past S3's 1000-key response cap, so a+ large prefix is not silently truncated.+ """+ prefix = self._to_key(path) if path else self.root_prefix+ if prefix:+ prefix = prefix if prefix.endswith("/") else f"{prefix}/"++ base = self._bucket_base_url()+ results: list[StorageObject] = []+ continuation: str | None = None++ for _ in range(_LIST_PAGE_GUARD):+ params = {"list-type": "2", "delimiter": "/"}+ if prefix:+ params["prefix"] = prefix+ if continuation:+ params["continuation-token"] = continuation++ url = str(httpx.URL(f"{base}/", params=params))++ async def fetch(target: str = url) -> httpx.Response:+ response = await self._http().get(target, headers=self._sign("GET", target))+ if response.is_error:+ raise self._map_error(response, response.text)+ return response++ response = await with_retry(fetch)+ root = ElementTree.fromstring(response.text)++ for prefix_node in root.iter(f"{_S3_NS}CommonPrefixes"):+ folder = _text(prefix_node, "Prefix")+ if folder:+ trimmed = folder.rstrip("/")+ virtual_folder = self._to_virtual_path(trimmed)+ results.append(+ StorageObject(+ id=f"s3_{self.bucket}_{trimmed}",+ path=virtual_folder,+ name=get_basename(virtual_folder),+ provider=PROVIDER_ID,+ provider_id=trimmed,+ type="folder",+ )+ )++ for item in root.iter(f"{_S3_NS}Contents"):+ key = _text(item, "Key")+ if not key or key == prefix:+ continue+ size = _text(item, "Size")+ modified = _text(item, "LastModified")+ virtual_key = self._to_virtual_path(key)+ results.append(+ StorageObject(+ id=f"s3_{self.bucket}_{key}",+ path=virtual_key,+ name=get_basename(virtual_key),+ provider=PROVIDER_ID,+ provider_id=key,+ type="file",+ size=int(size) if size else None,+ checksum=(_text(item, "ETag") or "").strip('"') or None,+ updated_at=datetime.fromisoformat(modified.replace("Z", "+00:00"))+ if modified+ else None,+ )+ )++ truncated = (_text(root, "IsTruncated") or "false").lower() == "true"+ continuation = _text(root, "NextContinuationToken") if truncated else None+ if not continuation:+ break++ return resultsdiff --git a/python/src/byoc/providers/webdav.py b/python/src/byoc/providers/webdav.pynew file mode 100644index 0000000..0615552--- /dev/null+++ b/python/src/byoc/providers/webdav.py@@ -0,0 +1,530 @@+"""WebDAV provider adapter.++Targets Nextcloud, ownCloud, Synology NAS, and any RFC 4918 server. WebDAV+collections, multistatus XML, and HTTP method verbs stay private to this module.++Unlike S3, WebDAV has real folders, so an upload creates missing ancestors with+MKCOL before writing.+"""++from __future__ import annotations++import base64+import contextlib+from collections.abc import AsyncIterator+from datetime import datetime+from email.utils import parsedate_to_datetime+from urllib.parse import unquote, urlsplit+from xml.etree import ElementTree++import httpx++from ..errors import (+ ConflictError,+ InvalidInputError,+ ObjectNotFoundError,+ PermissionDeniedError,+ ProviderUnavailableError,+ RateLimitedError,+ StorageError,+)+from ..paths import encode_path_segments, get_basename, get_dirname, normalize_virtual_path+from ..retry import with_retry+from ..types import (+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+)++PROVIDER_ID = "webdav"+_DAV = "{DAV:}"++_PROPFIND_BODY = """<?xml version="1.0" encoding="utf-8"?>+<d:propfind xmlns:d="DAV:">+ <d:prop>+ <d:resourcetype/>+ <d:getcontentlength/>+ <d:getcontenttype/>+ <d:getlastmodified/>+ <d:getetag/>+ </d:prop>+</d:propfind>"""++_QUOTA_BODY = """<?xml version="1.0" encoding="utf-8"?>+<d:propfind xmlns:d="DAV:">+ <d:prop>+ <d:quota-available-bytes/>+ <d:quota-used-bytes/>+ </d:prop>+</d:propfind>"""+++def _prop(response_el: ElementTree.Element, tag: str) -> str | None:+ """Read a DAV property from a multistatus <response> element."""+ for propstat in response_el.findall(f"{_DAV}propstat"):+ status = propstat.findtext(f"{_DAV}status") or ""+ if "200" not in status:+ continue+ found = propstat.find(f"{_DAV}prop/{_DAV}{tag}")+ if found is not None and found.text is not None:+ return found.text+ return None+++def _is_collection(response_el: ElementTree.Element) -> bool:+ for propstat in response_el.findall(f"{_DAV}propstat"):+ resource_type = propstat.find(f"{_DAV}prop/{_DAV}resourcetype")+ if resource_type is not None and resource_type.find(f"{_DAV}collection") is not None:+ return True+ return False+++class WebDAVProvider:+ """Storage adapter for WebDAV servers.++ Args:+ endpoint: Collection URL, e.g.+ ``https://cloud.example.com/remote.php/dav/files/alex/``.+ username: Username for Basic auth.+ password: Password for Basic auth. Use an app password, not the account+ password -- app passwords are scoped and independently revocable.+ token: Bearer token, as an alternative to username/password.+ root_folder: Folder inside the endpoint that all paths live under.+ client: An existing ``httpx.AsyncClient`` to reuse.+ """++ def __init__(+ self,+ *,+ endpoint: str,+ username: str | None = None,+ password: str | None = None,+ token: str | None = None,+ root_folder: str | None = "BYOC",+ client: httpx.AsyncClient | None = None,+ ) -> None:+ if not endpoint:+ raise InvalidInputError(+ "WebDAVProvider requires an 'endpoint' URL.", provider=PROVIDER_ID+ )++ self.endpoint = endpoint.rstrip("/")+ self.username = username+ self.password = password+ self.token = token+ self.root_folder = normalize_virtual_path(root_folder) if root_folder else ""++ self._base_path = urlsplit(self.endpoint).path.rstrip("/")+ self._client = client+ self._owns_client = client is None++ # -- lifecycle ---------------------------------------------------------++ def manifest(self) -> ProviderManifest:+ return ProviderManifest(+ id=PROVIDER_ID,+ name="Nextcloud / WebDAV",+ category="self-hosted",+ authentication="oauth2" if self.token else "basic",+ supports_user_owned_storage=True,+ adapter_version="0.2.0",+ )++ def capabilities(self) -> ProviderCapabilities:+ # WebDAV has real collections and RFC 4331 quota, but no resumable+ # upload protocol: large files go as a single PUT.+ return ProviderCapabilities(+ folders=True,+ sharing=False,+ public_urls=False,+ resumable_uploads=False,+ versioning=False,+ quota=True,+ server_side_copy=True,+ )++ async def connect(self) -> None:+ """Ensure the root folder exists, tolerating one that already does."""+ if self.root_folder:+ with contextlib.suppress(StorageError):+ await self._mkcol(self.root_folder)++ async def disconnect(self) -> None:+ if self._owns_client and self._client is not None:+ await self._client.aclose()+ self._client = None++ def _http(self) -> httpx.AsyncClient:+ if self._client is None:+ self._client = httpx.AsyncClient(timeout=httpx.Timeout(30.0, read=300.0))+ self._owns_client = True+ return self._client++ def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:+ headers = dict(extra or {})+ if self.token:+ headers["Authorization"] = f"Bearer {self.token}"+ elif self.username is not None and self.password is not None:+ raw = f"{self.username}:{self.password}".encode()+ headers["Authorization"] = f"Basic {base64.b64encode(raw).decode('ascii')}"+ return headers++ # -- path handling -----------------------------------------------------++ def _to_remote(self, path: str) -> str:+ """Virtual path -> path relative to the endpoint (adds ``root_folder``)."""+ normalized = normalize_virtual_path(path)+ if not self.root_folder:+ return normalized+ return f"{self.root_folder}/{normalized}" if normalized else self.root_folder++ def _to_virtual_path(self, remote: str) -> str:+ """Endpoint-relative path -> virtual path (strips ``root_folder``).++ ``root_folder`` is the adapter's business and must not appear in a+ returned ``StorageObject.path``, or a caller feeding that path back in+ would have the folder applied twice.+ """+ if self.root_folder and remote.startswith(f"{self.root_folder}/"):+ return remote[len(self.root_folder) + 1 :]+ if remote == self.root_folder:+ return ""+ return remote++ def _url(self, remote_path: str) -> str:+ encoded = encode_path_segments(remote_path)+ return f"{self.endpoint}/{encoded}" if encoded else self.endpoint++ def _href_to_remote(self, href: str) -> str:+ """Turn a multistatus href into an endpoint-relative path.++ Servers return hrefs either absolute or path-only, always percent-encoded.+ """+ path = unquote(urlsplit(href).path)+ if self._base_path and path.startswith(self._base_path):+ path = path[len(self._base_path) :]+ return path.strip("/")++ # -- error mapping -----------------------------------------------------++ def _map_error(self, response: httpx.Response) -> StorageError:+ status = response.status_code+ if status == 404:+ return ObjectNotFoundError(+ "WebDAV resource not found (HTTP 404).", provider=PROVIDER_ID, status_code=404+ )+ if status in (401, 403):+ return PermissionDeniedError(+ "WebDAV access denied: check credentials or use an app password.",+ provider=PROVIDER_ID,+ status_code=status,+ )+ if status in (405, 409, 412):+ return ConflictError(+ f"WebDAV conflict (HTTP {status}): the parent collection may not exist.",+ provider=PROVIDER_ID,+ status_code=status,+ )+ if status == 429:+ return RateLimitedError(+ "WebDAV rate limit exceeded.", provider=PROVIDER_ID, status_code=status+ )+ return ProviderUnavailableError(+ f"WebDAV error (HTTP {status}): {response.text[:300]}",+ provider=PROVIDER_ID,+ status_code=status,+ retryable=status >= 500,+ )++ def _object_from_response(self, remote: str, response: httpx.Response) -> StorageObject:+ virtual = self._to_virtual_path(remote)+ length = response.headers.get("content-length")+ last_modified = response.headers.get("last-modified")++ updated_at: datetime | None = None+ if last_modified:+ try:+ updated_at = parsedate_to_datetime(last_modified)+ except (TypeError, ValueError):+ updated_at = None++ return StorageObject(+ id=f"webdav_{remote}",+ path=virtual,+ name=get_basename(virtual) or get_basename(remote),+ provider=PROVIDER_ID,+ provider_id=remote,+ type="file",+ size=int(length) if length is not None else None,+ mime_type=response.headers.get("content-type"),+ checksum=(response.headers.get("etag") or "").strip('"') or None,+ updated_at=updated_at,+ )++ def _object_from_propfind(+ self, remote: str, entry: ElementTree.Element+ ) -> StorageObject:+ """Build a StorageObject from one multistatus <response> element."""+ is_folder = _is_collection(entry)+ size = _prop(entry, "getcontentlength")+ modified = _prop(entry, "getlastmodified")++ updated_at: datetime | None = None+ if modified:+ try:+ updated_at = parsedate_to_datetime(modified)+ except (TypeError, ValueError):+ updated_at = None++ virtual = self._to_virtual_path(remote)+ return StorageObject(+ id=f"webdav_{remote}",+ path=virtual,+ name=get_basename(virtual) or get_basename(remote),+ provider=PROVIDER_ID,+ provider_id=remote,+ type="folder" if is_folder else "file",+ size=int(size) if size and not is_folder else None,+ mime_type=_prop(entry, "getcontenttype"),+ checksum=(_prop(entry, "getetag") or "").strip('"') or None,+ updated_at=updated_at,+ )++ # -- WebDAV verbs ------------------------------------------------------++ async def _mkcol(self, remote: str) -> None:+ url = self._url(remote)+ response = await self._http().request("MKCOL", url, headers=self._headers())+ # 405 means the collection already exists, which is the desired state.+ if response.is_error and response.status_code != 405:+ raise self._map_error(response)++ async def _ensure_parents(self, remote_dir: str) -> None:+ """Create each missing ancestor collection, outermost first."""+ if not remote_dir:+ return+ segments = remote_dir.split("/")+ for index in range(1, len(segments) + 1):+ try:+ await self._mkcol("/".join(segments[:index]))+ except StorageError:+ # A parent that already exists is fine; a real failure surfaces+ # on the PUT that follows.+ continue++ # -- operations --------------------------------------------------------++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ remote = self._to_remote(path)+ await self._ensure_parents(get_dirname(remote))++ if isinstance(data, str):+ payload = data.encode("utf-8")+ elif isinstance(data, bytes | bytearray | memoryview):+ payload = bytes(data)+ else:+ raise InvalidInputError(+ "WebDAV upload requires bytes or str. Streaming uploads are not yet supported.",+ provider=PROVIDER_ID,+ )++ mime = (options.mime_type if options else None) or "application/octet-stream"+ url = self._url(remote)++ async def send() -> StorageObject:+ response = await self._http().put(+ url, headers=self._headers({"content-type": mime}), content=payload+ )+ if response.is_error:+ raise self._map_error(response)++ return StorageObject(+ id=f"webdav_{remote}",+ path=self._to_virtual_path(remote),+ name=get_basename(remote),+ provider=PROVIDER_ID,+ provider_id=remote,+ type="file",+ size=len(payload),+ mime_type=mime,+ checksum=(response.headers.get("etag") or "").strip('"') or None,+ )++ return await with_retry(send)++ async def download(self, path: str) -> StorageOutput:+ remote = self._to_remote(path)+ url = self._url(remote)++ async def fetch() -> httpx.Response:+ response = await self._http().get(url, headers=self._headers())+ if response.is_error:+ raise self._map_error(response)+ return response++ response = await with_retry(fetch)+ body = response.content++ async def stream() -> AsyncIterator[bytes]:+ yield body++ async def read() -> bytes:+ return body++ return StorageOutput(+ metadata=self._object_from_response(remote, response), stream=stream, read=read+ )++ async def delete(self, path: str) -> None:+ remote = self._to_remote(path)+ url = self._url(remote)++ async def send() -> None:+ response = await self._http().request("DELETE", url, headers=self._headers())+ if response.is_error and response.status_code != 404:+ raise self._map_error(response)++ await with_retry(send)++ async def metadata(self, path: str) -> StorageObject:+ """Read properties with ``PROPFIND`` at ``Depth: 0``.++ PROPFIND rather than HEAD: it is the canonical WebDAV way to read+ properties, returns size/type/etag/mtime uniformly across servers, and+ avoids a real interop hazard -- some servers attach an HTML error body+ to a HEAD 404, which desynchronizes a keep-alive connection and makes+ the *next* request on it fail with a bogus parse error.+ """+ remote = self._to_remote(path)+ url = self._url(remote)++ async def send() -> StorageObject:+ response = await self._http().request(+ "PROPFIND",+ url,+ headers=self._headers({"Depth": "0", "content-type": "application/xml"}),+ content=_PROPFIND_BODY.encode("utf-8"),+ )+ if response.is_error:+ raise self._map_error(response)++ root = ElementTree.fromstring(response.text)+ entry = root.find(f"{_DAV}response")+ if entry is None:+ raise ObjectNotFoundError(+ f"WebDAV resource not found: {path}", provider=PROVIDER_ID, status_code=404+ )++ return self._object_from_propfind(remote, entry)++ return await with_retry(send)++ async def exists(self, path: str) -> bool:+ try:+ await self.metadata(path)+ except ObjectNotFoundError:+ return False+ return True++ async def list(self, path: str | None = None) -> list[StorageObject]:+ """List one level below ``path`` via PROPFIND with ``Depth: 1``."""+ remote = self._to_remote(path or "")+ url = self._url(remote)++ async def fetch() -> httpx.Response:+ response = await self._http().request(+ "PROPFIND",+ url,+ headers=self._headers({"Depth": "1", "content-type": "application/xml"}),+ content=_PROPFIND_BODY.encode("utf-8"),+ )+ if response.is_error:+ raise self._map_error(response)+ return response++ response = await with_retry(fetch)+ root = ElementTree.fromstring(response.text)+ results: list[StorageObject] = []++ for entry in root.findall(f"{_DAV}response"):+ href = entry.findtext(f"{_DAV}href") or ""+ entry_remote = self._href_to_remote(href)++ # PROPFIND includes the collection itself; only children are listed.+ if entry_remote == remote or not entry_remote:+ continue++ results.append(self._object_from_propfind(entry_remote, entry))++ return results++ async def create_folder(self, path: str) -> StorageObject:+ remote = self._to_remote(path)+ await self._ensure_parents(remote)+ return StorageObject(+ id=f"webdav_{remote}",+ path=self._to_virtual_path(remote),+ name=get_basename(remote),+ provider=PROVIDER_ID,+ provider_id=remote,+ type="folder",+ )++ async def move(self, source: str, destination: str) -> None:+ """Server-side move (RFC 4918 MOVE), no bytes transferred."""+ target = self._to_remote(destination)+ await self._ensure_parents(get_dirname(target))+ response = await self._http().request(+ "MOVE",+ self._url(self._to_remote(source)),+ headers=self._headers({"Destination": self._url(target), "Overwrite": "T"}),+ )+ if response.is_error:+ raise self._map_error(response)++ async def copy(self, source: str, destination: str) -> None:+ """Server-side copy (RFC 4918 COPY), no bytes transferred."""+ target = self._to_remote(destination)+ await self._ensure_parents(get_dirname(target))+ response = await self._http().request(+ "COPY",+ self._url(self._to_remote(source)),+ headers=self._headers({"Destination": self._url(target), "Overwrite": "T"}),+ )+ if response.is_error:+ raise self._map_error(response)++ async def quota(self) -> StorageQuota:+ """Report quota via RFC 4331 properties, where the server supplies them."""+ response = await self._http().request(+ "PROPFIND",+ self._url(self._to_remote("")),+ headers=self._headers({"Depth": "0", "content-type": "application/xml"}),+ content=_QUOTA_BODY.encode("utf-8"),+ )+ if response.is_error:+ raise self._map_error(response)++ root = ElementTree.fromstring(response.text)+ entry = root.find(f"{_DAV}response")+ if entry is None:+ return StorageQuota(used=0)++ used_text = _prop(entry, "quota-used-bytes")+ available_text = _prop(entry, "quota-available-bytes")++ used = int(used_text) if used_text and used_text.lstrip("-").isdigit() else 0+ available: int | None = None+ if available_text and available_text.lstrip("-").isdigit():+ candidate = int(available_text)+ # Negative values are RFC 4331 sentinels for "unlimited"/"unknown".+ available = candidate if candidate >= 0 else None++ total = used + available if available is not None else None+ return StorageQuota(used=used, total=total, available=available)diff --git a/python/src/byoc/py.typed b/python/src/byoc/py.typednew file mode 100644index 0000000..e69de29diff --git a/python/src/byoc/retry.py b/python/src/byoc/retry.pynew file mode 100644index 0000000..f2843b7--- /dev/null+++ b/python/src/byoc/retry.py@@ -0,0 +1,58 @@+"""Retry with exponential backoff for transient provider failures."""++from __future__ import annotations++import asyncio+import random+from collections.abc import Awaitable, Callable+from typing import TypeVar++from .errors import StorageError++T = TypeVar("T")++DEFAULT_MAX_ATTEMPTS = 3+DEFAULT_BASE_DELAY_SECONDS = 0.25+DEFAULT_MAX_DELAY_SECONDS = 8.0+++def backoff_delay(+ attempt: int,+ base_delay: float = DEFAULT_BASE_DELAY_SECONDS,+ max_delay: float = DEFAULT_MAX_DELAY_SECONDS,+) -> float:+ """Return the delay before ``attempt`` (1-based), with full jitter.++ Jitter matters when many uploads are rate-limited at once: without it they+ all retry on the same schedule and re-trigger the limit together.+ """+ capped = min(max_delay, base_delay * (2 ** (attempt - 1)))+ # Jitter only; not security-sensitive randomness.+ return random.uniform(0, capped)+++async def with_retry(+ operation: Callable[[], Awaitable[T]],+ *,+ max_attempts: int = DEFAULT_MAX_ATTEMPTS,+ base_delay: float = DEFAULT_BASE_DELAY_SECONDS,+ max_delay: float = DEFAULT_MAX_DELAY_SECONDS,+) -> T:+ """Run ``operation``, retrying only errors the provider marked retryable.++ A non-retryable failure (bad credentials, missing object) is raised+ immediately rather than burning attempts on something that cannot succeed.+ """+ last_error: BaseException | None = None++ for attempt in range(1, max_attempts + 1):+ try:+ return await operation()+ except StorageError as exc:+ if not exc.retryable or attempt == max_attempts:+ raise+ last_error = exc+ await asyncio.sleep(backoff_delay(attempt, base_delay, max_delay))++ # Unreachable: the loop either returns or raises.+ raise last_error if last_error else RuntimeError("with_retry exhausted without an error")diff --git a/python/src/byoc/types.py b/python/src/byoc/types.pynew file mode 100644index 0000000..3a136c1--- /dev/null+++ b/python/src/byoc/types.py@@ -0,0 +1,187 @@+"""Provider-neutral types shared by every BYOC adapter.++These mirror the semantics of the TypeScript SDK's types, but not its spelling:+field names are ``snake_case`` because that is what Python callers expect. Only+values that cross into provider storage -- see ``spec/fixtures/provider-metadata.json``+-- keep their original casing.+"""++from __future__ import annotations++from collections.abc import AsyncIterator, Awaitable, Callable, Mapping+from dataclasses import dataclass, field+from datetime import datetime+from enum import Enum+from typing import Any, Literal, Protocol, runtime_checkable++ProviderCategory = Literal["personal-cloud", "self-hosted", "developer-cloud"]+AuthType = Literal["oauth2", "access-key", "basic", "local"]+ObjectType = Literal["file", "folder"]++StorageInput = bytes | bytearray | memoryview | str | AsyncIterator[bytes]+"""Accepted upload payloads. Async iterators of bytes stream without buffering."""+++class ConflictStrategy(str, Enum):+ """How a migration resolves a file that already exists on the target."""++ OVERWRITE = "overwrite"+ SKIP = "skip"+ ERROR = "error"++ def __str__(self) -> str:+ return self.value+++@dataclass(frozen=True, slots=True)+class StorageObject:+ """A file or folder in any BYOC storage backend."""++ id: str+ path: str+ name: str+ provider: str+ provider_id: str+ type: ObjectType | None = None+ size: int | None = None+ mime_type: str | None = None+ checksum: str | None = None+ created_at: datetime | None = None+ updated_at: datetime | None = None+ metadata: Mapping[str, Any] = field(default_factory=dict)+++@dataclass(frozen=True, slots=True)+class StorageQuota:+ """Storage quota reported by the provider. ``None`` means the provider did not say."""++ used: int+ total: int | None = None+ available: int | None = None+++@dataclass(frozen=True, slots=True)+class UploadProgress:+ """Progress event emitted during chunked or resumable uploads."""++ bytes_uploaded: int+ total_bytes: int | None = None+ percentage: float | None = None+++ProgressCallback = Callable[[UploadProgress], None]+++@dataclass(frozen=True, slots=True)+class UploadOptions:+ """Per-upload configuration."""++ mime_type: str | None = None+ resumable: bool | None = None+ chunk_size: int | None = None+ on_progress: ProgressCallback | None = None+ metadata: Mapping[str, str] = field(default_factory=dict)+++@dataclass(frozen=True, slots=True)+class BackupOptions:+ """Configuration for the high-level backup helper."""++ filename: str | None = None+ folder: str | None = None+ mime_type: str | None = None+ on_progress: ProgressCallback | None = None+++@dataclass(frozen=True, slots=True)+class ProviderManifest:+ """Static metadata identifying a provider adapter."""++ id: str+ name: str+ category: ProviderCategory+ authentication: AuthType+ supports_user_owned_storage: bool+ adapter_version: str+++@dataclass(frozen=True, slots=True)+class ProviderCapabilities:+ """What a provider can do, so callers feature-detect instead of guessing."""++ folders: bool = False+ sharing: bool = False+ public_urls: bool = False+ resumable_uploads: bool = False+ versioning: bool = False+ quota: bool = False+ server_side_copy: bool = False+++@dataclass(frozen=True, slots=True)+class StorageOutput:+ """A downloaded object: its metadata plus lazy accessors for the payload.++ ``stream`` yields chunks without buffering the whole object; ``read`` and+ ``text`` buffer it. Exactly one of them should be consumed.+ """++ metadata: StorageObject+ stream: Callable[[], AsyncIterator[bytes]]+ read: Callable[[], Awaitable[bytes]]++ async def text(self, encoding: str = "utf-8") -> str:+ """Buffer the payload and decode it."""+ return (await self.read()).decode(encoding)+++@runtime_checkable+class BYOCProvider(Protocol):+ """The interface every storage adapter implements.++ Optional operations (``create_folder``, ``move``, ``copy``, ``quota``) are+ declared on the matching :class:`ProviderCapabilities` flag. Callers should+ check the flag rather than probing for the attribute.+ """++ def manifest(self) -> ProviderManifest:+ """Return metadata identifying this provider."""+ ...++ def capabilities(self) -> ProviderCapabilities:+ """Return the feature flags this provider instance supports."""+ ...++ async def connect(self) -> None:+ """Establish or verify the session with the storage backend."""+ ...++ async def disconnect(self) -> None:+ """Tear down the session and clear any cached credentials."""+ ...++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ """Write ``data`` to ``path``."""+ ...++ async def download(self, path: str) -> StorageOutput:+ """Read the object at ``path``."""+ ...++ async def delete(self, path: str) -> None:+ """Remove the object at ``path``."""+ ...++ async def list(self, path: str | None = None) -> list[StorageObject]:+ """List objects directly under ``path``, or under the root if omitted."""+ ...++ async def exists(self, path: str) -> bool:+ """Return whether an object exists at ``path``."""+ ...++ async def metadata(self, path: str) -> StorageObject:+ """Return metadata for the object at ``path``."""+ ...diff --git a/python/tests/conftest.py b/python/tests/conftest.pynew file mode 100644index 0000000..911d0a1--- /dev/null+++ b/python/tests/conftest.py@@ -0,0 +1,21 @@+"""Shared fixture loading for the BYOC Python conformance suite.++Loads the same JSON vectors under ``/spec/fixtures`` that the TypeScript SDK+runs against. A failure here means this implementation has drifted from the+cross-SDK contract.+"""++from __future__ import annotations++import json+from pathlib import Path+from typing import Any++FIXTURE_DIR = Path(__file__).resolve().parents[2] / "spec" / "fixtures"+++def load_fixture(name: str) -> dict[str, Any]:+ """Load a conformance fixture by filename."""+ with (FIXTURE_DIR / name).open(encoding="utf-8") as handle:+ data: dict[str, Any] = json.load(handle)+ return datadiff --git a/python/tests/integration/__init__.py b/python/tests/integration/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/python/tests/integration/test_client_minio.py b/python/tests/integration/test_client_minio.pynew file mode 100644index 0000000..b7ed686--- /dev/null+++ b/python/tests/integration/test_client_minio.py@@ -0,0 +1,139 @@+"""AsyncBYOC driven against a real S3 server.++The unit tests exercise the client against an in-memory provider; this proves+the same code paths work when the provider is doing real HTTP, real signing, and+real error mapping.+"""++from __future__ import annotations++import uuid+from collections.abc import AsyncIterator++import pytest+import pytest_asyncio++from byoc import AsyncBYOC, ConflictStrategy+from byoc.errors import CapabilityUnsupportedError, ObjectNotFoundError+from byoc.providers.s3 import S3CompatibleProvider++from .test_s3_minio import (+ ACCESS_KEY,+ BUCKET,+ ENDPOINT,+ REGION,+ SECRET_KEY,+ _ensure_bucket,+ requires_minio,+)++pytestmark = pytest.mark.integration+++def _provider(provider_prefix: str) -> S3CompatibleProvider:+ return S3CompatibleProvider(+ endpoint=ENDPOINT,+ bucket=BUCKET,+ region=REGION,+ access_key_id=ACCESS_KEY,+ secret_access_key=SECRET_KEY,+ root_prefix=provider_prefix,+ force_path_style=True,+ )+++@pytest_asyncio.fixture+async def storage() -> AsyncIterator[AsyncBYOC]:+ await _ensure_bucket()+ run = uuid.uuid4().hex[:8]+ client = AsyncBYOC(provider=_provider(f"client-{run}"), max_file_size_bytes=1_000_000)+ await client.connect()+ try:+ yield client+ finally:+ await client.disconnect()+++@requires_minio+async def test_write_and_read_text(storage: AsyncBYOC) -> None:+ await storage.write_text("docs/note.md", "# Live from MinIO")+ assert await storage.read_text("docs/note.md") == "# Live from MinIO"+++@requires_minio+async def test_mime_type_detection_survives_the_round_trip(storage: AsyncBYOC) -> None:+ await storage.write_bytes("images/logo.png", b"\x89PNG\r\n\x1a\n")+ meta = await storage.metadata("images/logo.png")+ assert meta.mime_type == "image/png"+++@requires_minio+async def test_exists_delete_and_list(storage: AsyncBYOC) -> None:+ await storage.write_text("docs/a.txt", "a")+ await storage.write_text("docs/b.txt", "bb")++ assert await storage.exists("docs/a.txt") is True+ listed = await storage.list("docs")+ assert sorted(o.name for o in listed) == ["a.txt", "b.txt"]++ await storage.delete("docs/a.txt")+ assert await storage.exists("docs/a.txt") is False+++@requires_minio+async def test_missing_object_raises_not_found(storage: AsyncBYOC) -> None:+ with pytest.raises(ObjectNotFoundError):+ await storage.read_text("docs/never-written.md")+++@requires_minio+async def test_unsupported_capabilities_raise(storage: AsyncBYOC) -> None:+ """S3 has no real folders and reports no quota; both must say so honestly."""+ with pytest.raises(CapabilityUnsupportedError):+ await storage.create_folder("docs")+ with pytest.raises(CapabilityUnsupportedError):+ await storage.get_quota()+++@requires_minio+async def test_backup_helper_writes_to_the_server(storage: AsyncBYOC) -> None:+ obj = await storage.backup(b'{"rows": 1}')+ assert obj.path.startswith("Backups/backup-")+ assert await storage.exists(obj.path) is True+++@requires_minio+async def test_migrate_between_two_live_prefixes() -> None:+ """Two S3 prefixes stand in for two clouds: the engine only sees providers."""+ await _ensure_bucket()+ run = uuid.uuid4().hex[:8]+ source = _provider(f"mig-src-{run}")+ target = _provider(f"mig-dst-{run}")++ client = AsyncBYOC(providers=[source, target])+ # Both adapters share the same manifest id, so register them distinctly by+ # driving the engine through the source/target adapters directly.+ from byoc.migration import migrate as run_migration++ await source.connect()+ await target.connect()+ try:+ await source.upload("reports/q3.pdf", b"PDF BYTES", None)+ await source.upload("reports/q4.pdf", b"MORE BYTES", None)++ report = await run_migration(+ source=source,+ target=target,+ paths=["reports/q3.pdf", "reports/q4.pdf"],+ conflict_strategy=ConflictStrategy.OVERWRITE,+ )++ assert report.files_migrated == 2+ assert report.files_failed == 0+ assert report.bytes_transferred == 19+ assert await target.exists("reports/q3.pdf") is True+ assert await (await target.download("reports/q4.pdf")).read() == b"MORE BYTES"+ finally:+ await source.disconnect()+ await target.disconnect()+ await client.disconnect()diff --git a/python/tests/integration/test_s3_minio.py b/python/tests/integration/test_s3_minio.pynew file mode 100644index 0000000..fda8a0c--- /dev/null+++ b/python/tests/integration/test_s3_minio.py@@ -0,0 +1,183 @@+"""Live S3 integration tests against a real MinIO server.++Mock transports prove what we *send*; only a real S3 implementation proves it+*accepts* our signatures. Every serious bug this adapter's TypeScript sibling+had -- header casing, query canonicalization, unencoded ``#`` in keys -- was+invisible to mocks and would have surfaced here on the first request.++Skipped automatically when MinIO is not reachable, so the default test run stays+offline. Start one with::++ docker run -p 9000:9000 -e MINIO_ROOT_USER=minioadmin \\+ -e MINIO_ROOT_PASSWORD=minioadmin minio/minio server /data+"""++from __future__ import annotations++import os+import uuid+from collections.abc import AsyncIterator++import httpx+import pytest+import pytest_asyncio++from byoc.errors import ObjectNotFoundError+from byoc.providers._sigv4 import sign_s3_request+from byoc.providers.s3 import S3CompatibleProvider++ENDPOINT = os.environ.get("BYOC_TEST_S3_ENDPOINT", "http://127.0.0.1:9000")+ACCESS_KEY = os.environ.get("BYOC_TEST_S3_ACCESS_KEY", "minioadmin")+SECRET_KEY = os.environ.get("BYOC_TEST_S3_SECRET_KEY", "minioadmin")+REGION = os.environ.get("BYOC_TEST_S3_REGION", "us-east-1")+BUCKET = os.environ.get("BYOC_TEST_S3_BUCKET", "byoc-integration")++pytestmark = pytest.mark.integration+++def _server_is_up() -> bool:+ try:+ httpx.get(f"{ENDPOINT}/minio/health/live", timeout=2.0)+ except httpx.HTTPError:+ return False+ return True+++requires_minio = pytest.mark.skipif(+ not _server_is_up(), reason=f"No S3-compatible server reachable at {ENDPOINT}"+)+++async def _ensure_bucket() -> None:+ """Create the test bucket, tolerating one that already exists."""+ url = f"{ENDPOINT}/{BUCKET}"+ headers = sign_s3_request(+ access_key_id=ACCESS_KEY,+ secret_access_key=SECRET_KEY,+ region=REGION,+ method="PUT",+ url=url,+ )+ async with httpx.AsyncClient(timeout=10.0) as client:+ response = await client.put(url, headers=headers)++ already_exists = any(+ marker in response.text for marker in ("BucketAlreadyOwnedByYou", "BucketAlreadyExists")+ )+ if response.is_error and not already_exists:+ raise AssertionError(+ f"Could not create bucket: HTTP {response.status_code} {response.text}"+ )+++@pytest_asyncio.fixture+async def provider() -> AsyncIterator[S3CompatibleProvider]:+ await _ensure_bucket()+ adapter = S3CompatibleProvider(+ endpoint=ENDPOINT,+ bucket=BUCKET,+ region=REGION,+ access_key_id=ACCESS_KEY,+ secret_access_key=SECRET_KEY,+ root_prefix=f"run-{uuid.uuid4().hex[:8]}",+ force_path_style=True,+ )+ await adapter.connect()+ try:+ yield adapter+ finally:+ await adapter.disconnect()+++@requires_minio+async def test_upload_download_roundtrip(provider: S3CompatibleProvider) -> None:+ await provider.upload("docs/hello.txt", "Hello from BYOC", None)+ out = await provider.download("docs/hello.txt")+ assert await out.text() == "Hello from BYOC"+ assert out.metadata.size == 15+++@requires_minio+ "filename",+ [+ "notes/draft#2.pdf",+ "notes/what?.txt",+ "Q3 report/a b.pdf",+ "docs/café/naïve.txt",+ "notes/Bob's Notes.pdf",+ "docs/a&b+c.txt",+ ],+)+async def test_awkward_filenames_roundtrip(provider: S3CompatibleProvider, filename: str) -> None:+ """The exact filenames that broke the TypeScript adapter before it was fixed."""+ await provider.upload(filename, f"content of {filename}", None)+ out = await provider.download(filename)+ assert await out.text() == f"content of {filename}"+++@requires_minio+async def test_exists_and_delete(provider: S3CompatibleProvider) -> None:+ await provider.upload("temp.txt", b"x", None)+ assert await provider.exists("temp.txt") is True++ await provider.delete("temp.txt")+ assert await provider.exists("temp.txt") is False++ # Deleting again must stay silent: S3 delete is idempotent.+ await provider.delete("temp.txt")+++@requires_minio+async def test_metadata_of_missing_object_raises(provider: S3CompatibleProvider) -> None:+ with pytest.raises(ObjectNotFoundError):+ await provider.metadata("never-written.txt")+++@requires_minio+async def test_list_returns_files_and_folders(provider: S3CompatibleProvider) -> None:+ await provider.upload("docs/a.txt", b"a", None)+ await provider.upload("docs/b.txt", b"bb", None)+ await provider.upload("docs/nested/c.txt", b"ccc", None)++ listed = await provider.list("docs")+ names = sorted(o.name for o in listed)+ assert names == ["a.txt", "b.txt", "nested"]++ by_name = {o.name: o for o in listed}+ assert by_name["nested"].type == "folder"+ assert by_name["b.txt"].size == 2+++@requires_minio+async def test_list_pagination_past_one_page(provider: S3CompatibleProvider) -> None:+ """Exercises the continuation-token loop against a real server."""+ for index in range(12):+ await provider.upload(f"many/file-{index:03d}.txt", b"x", None)++ listed = await provider.list("many")+ assert len([o for o in listed if o.type == "file"]) == 12+++@requires_minio+async def test_custom_metadata_roundtrips(provider: S3CompatibleProvider) -> None:+ from byoc.types import UploadOptions++ await provider.upload(+ "meta.txt", b"data", UploadOptions(mime_type="text/plain", metadata={"Author": "Alice"})+ )+ meta = await provider.metadata("meta.txt")+ assert meta.mime_type == "text/plain"+++@requires_minio+async def test_presigned_url_is_accepted_by_the_server(provider: S3CompatibleProvider) -> None:+ """A presigned URL must work with no Authorization header at all."""+ await provider.upload("shared/report.pdf", b"PDF BYTES", None)+ url = provider.presigned_url("shared/report.pdf", expires_in_seconds=300)++ async with httpx.AsyncClient(timeout=10.0) as client:+ response = await client.get(url)++ assert response.status_code == 200, response.text+ assert response.content == b"PDF BYTES"diff --git a/python/tests/integration/test_webdav_live.py b/python/tests/integration/test_webdav_live.pynew file mode 100644index 0000000..66c872a--- /dev/null+++ b/python/tests/integration/test_webdav_live.py@@ -0,0 +1,204 @@+"""Live WebDAV integration tests against a real RFC 4918 server.++Runs an in-process ``wsgidav`` server, so these execute anywhere without Docker.+That matters: PROPFIND multistatus parsing, MKCOL ancestor creation, and href+decoding are all things a mock would happily accept while a real server+rejected them.++Point the suite at Nextcloud or ownCloud instead by setting+``BYOC_TEST_WEBDAV_ENDPOINT`` (plus ``_USERNAME`` / ``_PASSWORD``).+"""++from __future__ import annotations++import os+import tempfile+import threading+import uuid+from collections.abc import AsyncIterator, Iterator++import pytest+import pytest_asyncio++from byoc import AsyncBYOC+from byoc.errors import ObjectNotFoundError, PermissionDeniedError+from byoc.providers.webdav import WebDAVProvider++pytestmark = pytest.mark.integration++EXTERNAL_ENDPOINT = os.environ.get("BYOC_TEST_WEBDAV_ENDPOINT")+USERNAME = os.environ.get("BYOC_TEST_WEBDAV_USERNAME", "byoc")+PASSWORD = os.environ.get("BYOC_TEST_WEBDAV_PASSWORD", "byoc-secret")++[email protected](scope="module")+def webdav_endpoint() -> Iterator[str]:+ """Yield a WebDAV endpoint, starting a local server unless one is configured."""+ if EXTERNAL_ENDPOINT:+ yield EXTERNAL_ENDPOINT.rstrip("/")+ return++ from cheroot import wsgi+ from wsgidav.wsgidav_app import WsgiDAVApp++ root = tempfile.mkdtemp(prefix="byoc-webdav-")+ app = WsgiDAVApp(+ {+ "provider_mapping": {"/": root},+ "simple_dc": {"user_mapping": {"*": {USERNAME: {"password": PASSWORD}}}},+ "http_authenticator": {"accept_basic": True, "accept_digest": False},+ "verbose": 0,+ "logging": {"enable": False},+ }+ )+ server = wsgi.Server(bind_addr=("127.0.0.1", 0), wsgi_app=app)+ server.prepare()+ port = server.bind_addr[1]++ thread = threading.Thread(target=server.serve, daemon=True)+ thread.start()+ try:+ yield f"http://127.0.0.1:{port}"+ finally:+ server.stop()+++@pytest_asyncio.fixture+async def provider(webdav_endpoint: str) -> AsyncIterator[WebDAVProvider]:+ adapter = WebDAVProvider(+ endpoint=webdav_endpoint,+ username=USERNAME,+ password=PASSWORD,+ root_folder=f"byoc-{uuid.uuid4().hex[:8]}",+ )+ await adapter.connect()+ try:+ yield adapter+ finally:+ await adapter.disconnect()+++async def test_upload_download_roundtrip(provider: WebDAVProvider) -> None:+ await provider.upload("docs/hello.txt", "Hello from WebDAV", None)+ out = await provider.download("docs/hello.txt")+ assert await out.text() == "Hello from WebDAV"+ assert out.metadata.size == 17+++async def test_nested_folders_are_created_on_upload(provider: WebDAVProvider) -> None:+ """WebDAV PUT fails unless every ancestor collection already exists."""+ await provider.upload("a/b/c/d/deep.txt", b"deep", None)+ assert await provider.exists("a/b/c/d/deep.txt") is True+++ "filename",+ [+ "notes/draft#2.pdf",+ "notes/what?.txt",+ "Q3 report/a b.pdf",+ "docs/café/naïve.txt",+ "notes/Bob's Notes.pdf",+ "docs/a&b+c.txt",+ ],+)+async def test_awkward_filenames_roundtrip(provider: WebDAVProvider, filename: str) -> None:+ """Percent-encoding must survive both the PUT URL and the PROPFIND href."""+ await provider.upload(filename, f"content of {filename}", None)+ assert await (await provider.download(filename)).text() == f"content of {filename}"+++async def test_returned_paths_round_trip(provider: WebDAVProvider) -> None:+ """A returned path must be usable as an input path: root_folder must not leak."""+ obj = await provider.upload("docs/report.md", b"x", None)+ assert obj.path == "docs/report.md"+ assert await provider.exists(obj.path) is True+++async def test_exists_and_delete(provider: WebDAVProvider) -> None:+ await provider.upload("temp.txt", b"x", None)+ assert await provider.exists("temp.txt") is True++ await provider.delete("temp.txt")+ assert await provider.exists("temp.txt") is False+ # Deleting a missing file must stay silent.+ await provider.delete("temp.txt")+++async def test_metadata_of_missing_object_raises(provider: WebDAVProvider) -> None:+ with pytest.raises(ObjectNotFoundError):+ await provider.metadata("never-written.txt")+++async def test_list_returns_files_and_folders(provider: WebDAVProvider) -> None:+ await provider.upload("docs/a.txt", b"a", None)+ await provider.upload("docs/b.txt", b"bb", None)+ await provider.upload("docs/nested/c.txt", b"ccc", None)++ listed = await provider.list("docs")+ by_name = {o.name: o for o in listed}++ assert sorted(by_name) == ["a.txt", "b.txt", "nested"]+ assert by_name["nested"].type == "folder"+ assert by_name["b.txt"].type == "file"+ assert by_name["b.txt"].size == 2+ # Listed paths must be virtual, so they can be fed straight back in.+ assert by_name["a.txt"].path == "docs/a.txt"+++async def test_create_folder_and_list_it(provider: WebDAVProvider) -> None:+ await provider.create_folder("empty/deep")+ listed = await provider.list("empty")+ assert [o.name for o in listed] == ["deep"]+++async def test_server_side_move(provider: WebDAVProvider) -> None:+ await provider.upload("old/name.txt", b"payload", None)+ await provider.move("old/name.txt", "new/renamed.txt")++ assert await provider.exists("old/name.txt") is False+ assert await (await provider.download("new/renamed.txt")).read() == b"payload"+++async def test_server_side_copy(provider: WebDAVProvider) -> None:+ await provider.upload("src/original.txt", b"payload", None)+ await provider.copy("src/original.txt", "dst/duplicate.txt")++ assert await provider.exists("src/original.txt") is True+ assert await (await provider.download("dst/duplicate.txt")).read() == b"payload"+++async def test_quota_is_reported(provider: WebDAVProvider) -> None:+ quota = await provider.quota()+ assert quota.used >= 0+++async def test_through_the_byoc_client(webdav_endpoint: str) -> None:+ """The universal client over a live WebDAV backend."""+ storage = AsyncBYOC(+ provider=WebDAVProvider(+ endpoint=webdav_endpoint,+ username=USERNAME,+ password=PASSWORD,+ root_folder=f"client-{uuid.uuid4().hex[:8]}",+ )+ )+ async with storage:+ await storage.write_text("notes/todo.md", "# This week")+ assert await storage.read_text("notes/todo.md") == "# This week"++ # WebDAV declares folders and quota, unlike S3.+ assert storage.has_capability("folders") is True+ await storage.create_folder("archive")+ assert (await storage.get_quota()).used >= 0+++async def test_bad_credentials_are_rejected(webdav_endpoint: str) -> None:+ adapter = WebDAVProvider(+ endpoint=webdav_endpoint, username=USERNAME, password="wrong-password", root_folder="x"+ )+ try:+ with pytest.raises(PermissionDeniedError):+ await adapter.upload("denied.txt", b"x", None)+ finally:+ await adapter.disconnect()diff --git a/python/tests/interop/__init__.py b/python/tests/interop/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/python/tests/interop/interop_cli.mjs b/python/tests/interop/interop_cli.mjsnew file mode 100644index 0000000..01693f0--- /dev/null+++ b/python/tests/interop/interop_cli.mjs@@ -0,0 +1,130 @@+#!/usr/bin/env node+/**+ * TypeScript half of the cross-SDK interop suite.+ *+ * The Python suite shells out to this script so both SDKs act on the *same*+ * live storage server in one test run. Every command reads JSON on argv and+ * prints JSON on stdout, so the Python side never parses prose.+ *+ * Usage: node interop_cli.mjs <command> '<json-args>'+ */++const [, , command, rawArgs] = process.argv;+const args = rawArgs ? JSON.parse(rawArgs) : {};++const repoRoot = new URL("../../../", import.meta.url).pathname;+const load = (pkg) => import(`${repoRoot}packages/${pkg}/dist/index.js`);++const env = {+ s3Endpoint: process.env.BYOC_TEST_S3_ENDPOINT ?? "http://127.0.0.1:9000",+ s3Bucket: process.env.BYOC_TEST_S3_BUCKET ?? "byoc-integration",+ s3Region: process.env.BYOC_TEST_S3_REGION ?? "us-east-1",+ s3Key: process.env.BYOC_TEST_S3_ACCESS_KEY ?? "minioadmin",+ s3Secret: process.env.BYOC_TEST_S3_SECRET_KEY ?? "minioadmin",+ davEndpoint: process.env.BYOC_TEST_WEBDAV_ENDPOINT ?? "http://127.0.0.1:8099",+ davUser: process.env.BYOC_TEST_WEBDAV_USERNAME ?? "byoc",+ davPassword: process.env.BYOC_TEST_WEBDAV_PASSWORD ?? "byoc-secret"+};++async function s3Provider(rootPrefix) {+ const { S3CompatibleProvider } = await load("s3-compatible");+ return new S3CompatibleProvider({+ endpoint: env.s3Endpoint,+ bucket: env.s3Bucket,+ region: env.s3Region,+ accessKeyId: env.s3Key,+ secretAccessKey: env.s3Secret,+ rootPrefix,+ forcePathStyle: true+ });+}++async function davProvider(rootFolder) {+ const { WebDAVProvider } = await load("webdav");+ const provider = new WebDAVProvider({+ endpoint: env.davEndpoint,+ username: env.davUser,+ password: env.davPassword,+ rootFolder+ });+ await provider.connect();+ return provider;+}++const commands = {+ // --- storage round-trips ------------------------------------------------++ async write({ backend, root, files }) {+ const provider = backend === "s3" ? await s3Provider(root) : await davProvider(root);+ const written = [];+ for (const [path, content] of Object.entries(files)) {+ const obj = await provider.upload(path, content, { mimeType: "text/plain" });+ written.push({ path: obj.path, providerId: obj.providerId, size: obj.size });+ }+ return { written };+ },++ async read({ backend, root, paths }) {+ const provider = backend === "s3" ? await s3Provider(root) : await davProvider(root);+ const contents = {};+ for (const path of paths) {+ const out = await provider.download(path);+ contents[path] = await out.text();+ }+ return { contents };+ },++ async list({ backend, root, path }) {+ const provider = backend === "s3" ? await s3Provider(root) : await davProvider(root);+ const objects = await provider.list(path);+ return {+ objects: objects+ .map((o) => ({ path: o.path, name: o.name, type: o.type ?? null, size: o.size ?? null }))+ .sort((a, b) => a.path.localeCompare(b.path))+ };+ },++ // --- encryption ---------------------------------------------------------++ async encrypt({ passphrase, plaintext, iterations }) {+ const { E2EECrypto } = await load("core");+ const crypto = new E2EECrypto(+ iterations ? { passphrase, keyDerivationIterations: iterations } : { passphrase }+ );+ const envelope = await crypto.encrypt(plaintext);+ return { envelopeHex: Buffer.from(envelope).toString("hex") };+ },++ async decrypt({ passphrase, envelopeHex }) {+ const { E2EECrypto } = await load("core");+ const crypto = new E2EECrypto({ passphrase });+ const plaintext = await crypto.decrypt(Uint8Array.from(Buffer.from(envelopeHex, "hex")));+ return { plaintext: new TextDecoder().decode(plaintext) };+ },++ // --- pure functions, for spot-checking the shared fixtures --------------++ async normalize({ paths }) {+ const { normalizeVirtualPath, encodePathSegments } = await load("core");+ return {+ results: paths.map((p) => ({+ input: p,+ normalized: normalizeVirtualPath(p),+ encoded: encodePathSegments(normalizeVirtualPath(p))+ }))+ };+ }+};++const handler = commands[command];+if (!handler) {+ console.error(JSON.stringify({ error: `Unknown command: ${command}` }));+ process.exit(2);+}++try {+ process.stdout.write(JSON.stringify(await handler(args)));+} catch (err) {+ console.error(JSON.stringify({ error: String(err?.message ?? err), code: err?.code ?? null }));+ process.exit(1);+}diff --git a/python/tests/interop/test_cross_sdk.py b/python/tests/interop/test_cross_sdk.pynew file mode 100644index 0000000..8513f59--- /dev/null+++ b/python/tests/interop/test_cross_sdk.py@@ -0,0 +1,331 @@+"""Cross-SDK interop: the TypeScript and Python SDKs against the same servers.++This is the suite that justifies shipping both SDKs together. Friends will mix+them -- a Next.js frontend on ``@byoc/core`` and a FastAPI backend on ``byoc``,+both pointed at the same bucket. If a file written by one is not readable by the+other, that breaks silently in their projects, not here.++The TypeScript half runs through ``interop_cli.mjs``; both halves talk to the+same live MinIO and WebDAV servers.+"""++from __future__ import annotations++import json+import os+import shutil+import subprocess+import tempfile+import threading+import uuid+from collections.abc import Iterator+from pathlib import Path+from typing import Any++import httpx+import pytest++from byoc.encryption import E2EECrypto+from byoc.providers.s3 import S3CompatibleProvider+from byoc.providers.webdav import WebDAVProvider++pytestmark = pytest.mark.interop++CLI = Path(__file__).parent / "interop_cli.mjs"+REPO_ROOT = Path(__file__).resolve().parents[3]++S3_ENDPOINT = os.environ.get("BYOC_TEST_S3_ENDPOINT", "http://127.0.0.1:9000")+S3_BUCKET = os.environ.get("BYOC_TEST_S3_BUCKET", "byoc-integration")+S3_REGION = os.environ.get("BYOC_TEST_S3_REGION", "us-east-1")+S3_KEY = os.environ.get("BYOC_TEST_S3_ACCESS_KEY", "minioadmin")+S3_SECRET = os.environ.get("BYOC_TEST_S3_SECRET_KEY", "minioadmin")++DAV_USER = os.environ.get("BYOC_TEST_WEBDAV_USERNAME", "byoc")+DAV_PASSWORD = os.environ.get("BYOC_TEST_WEBDAV_PASSWORD", "byoc-secret")++# The filenames that have historically broken one adapter or the other.+AWKWARD_FILENAMES = [+ "notes/draft#2.pdf",+ "notes/what?.txt",+ "Q3 report/a b.pdf",+ "docs/café/naïve.txt",+ "notes/Bob's Notes.pdf",+ "docs/a&b+c.txt",+]+++def _node_available() -> bool:+ return shutil.which("node") is not None+++def _ts_built() -> bool:+ return (REPO_ROOT / "packages" / "core" / "dist" / "index.js").exists()+++def _s3_up() -> bool:+ try:+ httpx.get(f"{S3_ENDPOINT}/minio/health/live", timeout=2.0)+ except httpx.HTTPError:+ return False+ return True+++requires_interop = pytest.mark.skipif(+ not (_node_available() and _ts_built() and _s3_up()),+ reason="Interop needs node, a built TypeScript dist/, and a live S3 server",+)++[email protected](scope="module")+def dav_endpoint() -> Iterator[str]:+ """A WebDAV server both SDKs can reach, started locally unless configured."""+ external = os.environ.get("BYOC_TEST_WEBDAV_ENDPOINT")+ if external:+ yield external.rstrip("/")+ return++ from cheroot import wsgi+ from wsgidav.wsgidav_app import WsgiDAVApp++ root = tempfile.mkdtemp(prefix="byoc-interop-dav-")+ app = WsgiDAVApp(+ {+ "provider_mapping": {"/": root},+ "simple_dc": {"user_mapping": {"*": {DAV_USER: {"password": DAV_PASSWORD}}}},+ "http_authenticator": {"accept_basic": True, "accept_digest": False},+ "verbose": 0,+ "logging": {"enable": False},+ }+ )+ server = wsgi.Server(bind_addr=("127.0.0.1", 0), wsgi_app=app)+ server.prepare()+ port = server.bind_addr[1]+ threading.Thread(target=server.serve, daemon=True).start()+ try:+ yield f"http://127.0.0.1:{port}"+ finally:+ server.stop()+++def run_ts(command: str, args: dict[str, Any], dav_endpoint: str | None = None) -> dict[str, Any]:+ """Invoke the TypeScript SDK and return its JSON result."""+ env = {+ **os.environ,+ "BYOC_TEST_S3_ENDPOINT": S3_ENDPOINT,+ "BYOC_TEST_S3_BUCKET": S3_BUCKET,+ "BYOC_TEST_S3_REGION": S3_REGION,+ "BYOC_TEST_S3_ACCESS_KEY": S3_KEY,+ "BYOC_TEST_S3_SECRET_KEY": S3_SECRET,+ "BYOC_TEST_WEBDAV_USERNAME": DAV_USER,+ "BYOC_TEST_WEBDAV_PASSWORD": DAV_PASSWORD,+ }+ if dav_endpoint:+ env["BYOC_TEST_WEBDAV_ENDPOINT"] = dav_endpoint++ completed = subprocess.run(+ ["node", str(CLI), command, json.dumps(args)],+ capture_output=True,+ text=True,+ env=env,+ timeout=120,+ check=False,+ )+ if completed.returncode != 0:+ raise AssertionError(+ f"TypeScript CLI '{command}' failed ({completed.returncode}): "+ f"{completed.stderr.strip() or completed.stdout.strip()}"+ )+ result: dict[str, Any] = json.loads(completed.stdout)+ return result+++def py_s3(root_prefix: str) -> S3CompatibleProvider:+ return S3CompatibleProvider(+ endpoint=S3_ENDPOINT,+ bucket=S3_BUCKET,+ region=S3_REGION,+ access_key_id=S3_KEY,+ secret_access_key=S3_SECRET,+ root_prefix=root_prefix,+ force_path_style=True,+ )+++def py_dav(endpoint: str, root_folder: str) -> WebDAVProvider:+ return WebDAVProvider(+ endpoint=endpoint, username=DAV_USER, password=DAV_PASSWORD, root_folder=root_folder+ )+++# -- S3 ----------------------------------------------------------------------+++@requires_interop+async def test_s3_typescript_writes_python_reads() -> None:+ root = f"interop-{uuid.uuid4().hex[:8]}"+ files = {name: f"content of {name}" for name in AWKWARD_FILENAMES}++ run_ts("write", {"backend": "s3", "root": root, "files": files})++ provider = py_s3(root)+ try:+ for name, expected in files.items():+ assert await (await provider.download(name)).text() == expected+ finally:+ await provider.disconnect()+++@requires_interop+async def test_s3_python_writes_typescript_reads() -> None:+ root = f"interop-{uuid.uuid4().hex[:8]}"+ files = {name: f"content of {name}" for name in AWKWARD_FILENAMES}++ provider = py_s3(root)+ try:+ for name, content in files.items():+ await provider.upload(name, content, None)+ finally:+ await provider.disconnect()++ result = run_ts("read", {"backend": "s3", "root": root, "paths": list(files)})+ assert result["contents"] == files+++@requires_interop+async def test_s3_listing_agrees_across_sdks() -> None:+ """Both SDKs must report the same virtual paths, names, and types."""+ root = f"interop-{uuid.uuid4().hex[:8]}"+ files = {"docs/a.txt": "a", "docs/b.txt": "bb", "docs/nested/c.txt": "ccc"}+ run_ts("write", {"backend": "s3", "root": root, "files": files})++ ts_listing = run_ts("list", {"backend": "s3", "root": root, "path": "docs"})["objects"]++ provider = py_s3(root)+ try:+ py_objects = sorted(+ (+ {"path": o.path, "name": o.name, "type": o.type, "size": o.size}+ for o in await provider.list("docs")+ ),+ key=lambda o: str(o["path"]),+ )+ finally:+ await provider.disconnect()++ assert [o["path"] for o in py_objects] == [o["path"] for o in ts_listing]+ assert [o["type"] for o in py_objects] == [o["type"] for o in ts_listing]+++# -- WebDAV ------------------------------------------------------------------+++@requires_interop+async def test_webdav_typescript_writes_python_reads(dav_endpoint: str) -> None:+ root = f"interop-{uuid.uuid4().hex[:8]}"+ files = {name: f"content of {name}" for name in AWKWARD_FILENAMES}++ run_ts("write", {"backend": "webdav", "root": root, "files": files}, dav_endpoint)++ provider = py_dav(dav_endpoint, root)+ try:+ for name, expected in files.items():+ assert await (await provider.download(name)).text() == expected+ finally:+ await provider.disconnect()+++@requires_interop+async def test_webdav_python_writes_typescript_reads(dav_endpoint: str) -> None:+ root = f"interop-{uuid.uuid4().hex[:8]}"+ files = {name: f"content of {name}" for name in AWKWARD_FILENAMES}++ provider = py_dav(dav_endpoint, root)+ try:+ await provider.connect()+ for name, content in files.items():+ await provider.upload(name, content, None)+ finally:+ await provider.disconnect()++ result = run_ts(+ "read", {"backend": "webdav", "root": root, "paths": list(files)}, dav_endpoint+ )+ assert result["contents"] == files+++# -- Encryption --------------------------------------------------------------+++@requires_interop+def test_e2ee_typescript_encrypts_python_decrypts() -> None:+ """Without this, an encrypted file written by one SDK is lost to the other."""+ passphrase = "cross-sdk-interop-passphrase"+ plaintext = "Sensitive payload written by TypeScript."++ envelope_hex = run_ts("encrypt", {"passphrase": passphrase, "plaintext": plaintext})[+ "envelopeHex"+ ]+ envelope = bytes.fromhex(envelope_hex)++ assert envelope[:12] == b"BYOC_E2EE_V2"+ decrypted = E2EECrypto(passphrase=passphrase).decrypt_sync(envelope)+ assert decrypted.decode("utf-8") == plaintext+++@requires_interop+def test_e2ee_python_encrypts_typescript_decrypts() -> None:+ passphrase = "cross-sdk-interop-passphrase"+ plaintext = "Sensitive payload written by Python."++ envelope = E2EECrypto(passphrase=passphrase).encrypt_sync(plaintext)+ result = run_ts("decrypt", {"passphrase": passphrase, "envelopeHex": envelope.hex()})+ assert result["plaintext"] == plaintext+++@requires_interop[email protected]("iterations", [10_000, 100_000, 600_000, 2_000_000])+def test_e2ee_iteration_counts_interoperate(iterations: int) -> None:+ """The envelope carries its own work factor, so any valid count must cross."""+ passphrase = "iteration-interop"+ plaintext = f"encrypted with {iterations} iterations"++ envelope_hex = run_ts(+ "encrypt", {"passphrase": passphrase, "plaintext": plaintext, "iterations": iterations}+ )["envelopeHex"]++ envelope = bytes.fromhex(envelope_hex)+ assert int.from_bytes(envelope[12:16], "big") == iterations+ assert E2EECrypto(passphrase=passphrase).decrypt_sync(envelope).decode() == plaintext+++@requires_interop+def test_e2ee_wrong_passphrase_fails_the_same_way_across_sdks() -> None:+ envelope = E2EECrypto(passphrase="right").encrypt_sync("secret")+ with pytest.raises(AssertionError) as excinfo:+ run_ts("decrypt", {"passphrase": "wrong", "envelopeHex": envelope.hex()})+ assert "BYOC_AUTH_REQUIRED" in str(excinfo.value)+++# -- Pure functions ----------------------------------------------------------+++@requires_interop+def test_path_normalization_agrees_across_sdks() -> None:+ """A disagreement here means the two SDKs write to different folders."""+ from byoc.paths import encode_path_segments, normalize_virtual_path++ paths = [+ *AWKWARD_FILENAMES,+ "users///123////avatar.jpg",+ " /documents/report.pdf ",+ "./users/./123/avatar.jpg",+ "users\\123\\avatar.jpg",+ ]+ ts_results = run_ts("normalize", {"paths": paths})["results"]++ for entry in ts_results:+ normalized = normalize_virtual_path(entry["input"])+ assert normalized == entry["normalized"], f"normalize disagreed on {entry['input']!r}"+ assert encode_path_segments(normalized) == entry["encoded"], (+ f"encode disagreed on {entry['input']!r}"+ )diff --git a/python/tests/test_client.py b/python/tests/test_client.pynew file mode 100644index 0000000..712eeb9--- /dev/null+++ b/python/tests/test_client.py@@ -0,0 +1,358 @@+"""AsyncBYOC client and migration engine, driven by an in-memory provider."""++from __future__ import annotations++from collections.abc import AsyncIterator++import pytest++from byoc import AsyncBYOC, ConflictStrategy+from byoc.errors import CapabilityUnsupportedError, InvalidInputError+from byoc.types import (+ ProviderCapabilities,+ ProviderManifest,+ StorageInput,+ StorageObject,+ StorageOutput,+ StorageQuota,+ UploadOptions,+)+++class MemoryProvider:+ """Minimal in-memory BYOCProvider for exercising client behaviour."""++ def __init__(self, provider_id: str = "memory", *, folders: bool = True, quota: bool = True):+ self.id = provider_id+ self.store: dict[str, tuple[bytes, str | None]] = {}+ self.connected = False+ self.fail_delete = False+ self._folders = folders+ self._quota = quota++ def manifest(self) -> ProviderManifest:+ return ProviderManifest(+ id=self.id,+ name=f"Memory ({self.id})",+ category="self-hosted",+ authentication="basic",+ supports_user_owned_storage=True,+ adapter_version="0.2.0",+ )++ def capabilities(self) -> ProviderCapabilities:+ return ProviderCapabilities(folders=self._folders, quota=self._quota)++ async def connect(self) -> None:+ self.connected = True++ async def disconnect(self) -> None:+ self.connected = False++ async def upload(+ self, path: str, data: StorageInput, options: UploadOptions | None = None+ ) -> StorageObject:+ payload = data.encode("utf-8") if isinstance(data, str) else bytes(data) # type: ignore[arg-type]+ mime = options.mime_type if options else None+ self.store[path] = (payload, mime)+ return StorageObject(+ id=f"{self.id}_{path}",+ path=path,+ name=path.rsplit("/", 1)[-1],+ provider=self.id,+ provider_id=path,+ size=len(payload),+ mime_type=mime,+ )++ async def download(self, path: str) -> StorageOutput:+ if path not in self.store:+ from byoc.errors import ObjectNotFoundError++ raise ObjectNotFoundError(f"Not found: {path}", provider=self.id)+ payload, mime = self.store[path]++ async def stream() -> AsyncIterator[bytes]:+ yield payload++ async def read() -> bytes:+ return payload++ return StorageOutput(+ metadata=StorageObject(+ id=f"{self.id}_{path}",+ path=path,+ name=path.rsplit("/", 1)[-1],+ provider=self.id,+ provider_id=path,+ size=len(payload),+ mime_type=mime,+ ),+ stream=stream,+ read=read,+ )++ async def delete(self, path: str) -> None:+ if self.fail_delete:+ from byoc.errors import PermissionDeniedError++ raise PermissionDeniedError("read-only source", provider=self.id)+ self.store.pop(path, None)++ async def list(self, path: str | None = None) -> list[StorageObject]:+ prefix = f"{path}/" if path else ""+ return [+ StorageObject(+ id=f"{self.id}_{key}",+ path=key,+ name=key.rsplit("/", 1)[-1],+ provider=self.id,+ provider_id=key,+ )+ for key in self.store+ if key.startswith(prefix)+ ]++ async def exists(self, path: str) -> bool:+ return path in self.store++ async def metadata(self, path: str) -> StorageObject:+ return (await self.download(path)).metadata++ async def quota(self) -> StorageQuota:+ used = sum(len(v[0]) for v in self.store.values())+ return StorageQuota(used=used, total=1000, available=1000 - used)+++def test_requires_at_least_one_provider() -> None:+ with pytest.raises(InvalidInputError):+ AsyncBYOC()+++async def test_write_and_read_text_roundtrip() -> None:+ storage = AsyncBYOC(provider=MemoryProvider())+ await storage.connect()+ await storage.write_text("docs/note.md", "# Hello")+ assert await storage.read_text("docs/note.md") == "# Hello"+++async def test_paths_are_normalized_before_reaching_the_provider() -> None:+ provider = MemoryProvider()+ storage = AsyncBYOC(provider=provider)+ await storage.write_text("///docs//../..//".replace("..", "x"), "v")+ await storage.write_text("/docs//note.md/", "value")+ assert "docs/note.md" in provider.store+++async def test_upload_rejects_traversal() -> None:+ storage = AsyncBYOC(provider=MemoryProvider())+ with pytest.raises(InvalidInputError):+ await storage.write_text("../escape.txt", "nope")+++async def test_mime_type_is_detected_from_the_path() -> None:+ provider = MemoryProvider()+ storage = AsyncBYOC(provider=provider)+ obj = await storage.upload("images/logo.png", b"PNG")+ assert obj.mime_type == "image/png"+++async def test_max_file_size_is_enforced() -> None:+ storage = AsyncBYOC(provider=MemoryProvider(), max_file_size_bytes=4)+ with pytest.raises(InvalidInputError):+ await storage.write_bytes("big.bin", b"12345")+++async def test_exists_and_delete() -> None:+ storage = AsyncBYOC(provider=MemoryProvider())+ await storage.write_text("a.txt", "x")+ assert await storage.exists("a.txt") is True+ await storage.delete("a.txt")+ assert await storage.exists("a.txt") is False+ # An empty path is the root, never a file.+ assert await storage.exists("") is False+++async def test_provider_switching() -> None:+ drive = MemoryProvider("google-drive")+ s3 = MemoryProvider("s3-compatible")+ storage = AsyncBYOC(providers=[drive, s3], default_provider_id="s3-compatible")++ assert storage.manifest().id == "s3-compatible"+ await storage.write_text("only-on-s3.txt", "v")++ storage.use_provider("google-drive")+ assert storage.manifest().id == "google-drive"+ assert await storage.exists("only-on-s3.txt") is False++ assert sorted(m.id for m in storage.get_providers()) == ["google-drive", "s3-compatible"]+++async def test_unknown_provider_lists_the_available_ones() -> None:+ storage = AsyncBYOC(provider=MemoryProvider("memory"))+ with pytest.raises(InvalidInputError) as excinfo:+ storage.use_provider("dropbox")+ assert "memory" in str(excinfo.value)+++async def test_capability_gated_operations_raise_when_unsupported() -> None:+ storage = AsyncBYOC(provider=MemoryProvider(folders=False, quota=False))+ with pytest.raises(CapabilityUnsupportedError):+ await storage.create_folder("docs")+ with pytest.raises(CapabilityUnsupportedError):+ await storage.get_quota()+ # move() is absent from MemoryProvider entirely.+ with pytest.raises(CapabilityUnsupportedError):+ await storage.move("a.txt", "b.txt")+++async def test_quota_is_returned_when_supported() -> None:+ storage = AsyncBYOC(provider=MemoryProvider())+ await storage.write_bytes("a.bin", b"1234")+ quota = await storage.get_quota()+ assert quota.used == 4+ assert quota.available == 996+++async def test_backup_writes_a_timestamped_file() -> None:+ provider = MemoryProvider()+ storage = AsyncBYOC(provider=provider)+ obj = await storage.backup(b'{"rows":1}')+ assert obj.path.startswith("Backups/backup-")+ assert obj.path.endswith(".json")+++async def test_async_context_manager_connects_and_disconnects() -> None:+ provider = MemoryProvider()+ async with AsyncBYOC(provider=provider) as storage:+ assert provider.connected is True+ await storage.write_text("x.txt", "y")+ assert provider.connected is False+++# -- migration ---------------------------------------------------------------+++async def test_migrate_between_providers() -> None:+ source = MemoryProvider("google-drive")+ target = MemoryProvider("webdav")+ storage = AsyncBYOC(providers=[source, target])++ await source.upload("docs/a.txt", b"aaa")+ await source.upload("docs/b.txt", b"bb")++ report = await storage.migrate(+ source="google-drive", target="webdav", paths=["docs/a.txt", "docs/b.txt"]+ )++ assert report.files_total == 2+ assert report.files_migrated == 2+ assert report.files_failed == 0+ assert report.bytes_transferred == 5+ assert await target.exists("docs/a.txt")+++async def test_migrate_reports_partial_when_source_delete_fails() -> None:+ """The copy landed; only cleanup failed. Retrying would re-upload for nothing."""+ source = MemoryProvider("src")+ target = MemoryProvider("dst")+ source.fail_delete = True+ await source.upload("vault/key.pem", b"SECRET")++ storage = AsyncBYOC(providers=[source, target])+ report = await storage.migrate(+ source="src", target="dst", paths=["vault/key.pem"], delete_source_after_migrate=True+ )++ assert report.files_migrated == 0+ assert report.files_failed == 0+ assert report.files_partial == 1+ # Exactly one record for one input file: no double-counting.+ assert len(report.results) == 1+ assert report.results[0].status == "partial"++ # The point of 'partial': the target copy really exists...+ assert await target.exists("vault/key.pem")+ # ...and the source is still there, awaiting cleanup.+ assert await source.exists("vault/key.pem")+++async def test_migrate_reports_failed_when_the_upload_fails() -> None:+ source = MemoryProvider("src")+ target = MemoryProvider("dst")+ await source.upload("a.txt", b"x")++ async def boom(*args: object, **kwargs: object) -> StorageObject:+ raise RuntimeError("quota exceeded on target")++ target.upload = boom # type: ignore[assignment]++ storage = AsyncBYOC(providers=[source, target])+ report = await storage.migrate(+ source="src", target="dst", paths=["a.txt"], delete_source_after_migrate=True+ )++ assert report.files_failed == 1+ assert report.files_partial == 0+ # A real transfer failure must never delete the source.+ assert await source.exists("a.txt")+++async def test_migrate_skip_strategy() -> None:+ source = MemoryProvider("src")+ target = MemoryProvider("dst")+ await source.upload("a.txt", b"new")+ await target.upload("a.txt", b"old")++ storage = AsyncBYOC(providers=[source, target])+ report = await storage.migrate(+ source="src", target="dst", paths=["a.txt"], conflict_strategy=ConflictStrategy.SKIP+ )++ assert report.files_skipped == 1+ assert (await (await target.download("a.txt")).read()) == b"old"+++async def test_migrate_error_strategy_records_failure() -> None:+ source = MemoryProvider("src")+ target = MemoryProvider("dst")+ await source.upload("a.txt", b"new")+ await target.upload("a.txt", b"old")++ storage = AsyncBYOC(providers=[source, target])+ report = await storage.migrate(+ source="src", target="dst", paths=["a.txt"], conflict_strategy=ConflictStrategy.ERROR+ )+ assert report.files_failed == 1+++async def test_migrate_progress_reaches_one_hundred_percent() -> None:+ source = MemoryProvider("src")+ target = MemoryProvider("dst")+ for i in range(4):+ await source.upload(f"f{i}.txt", b"x")++ events: list[int] = []+ storage = AsyncBYOC(providers=[source, target])+ await storage.migrate(+ source="src",+ target="dst",+ paths=[f"f{i}.txt" for i in range(4)],+ on_progress=lambda p: events.append(p.percentage),+ )++ assert len(events) == 4+ assert events[-1] == 100+++async def test_migrate_unknown_provider_raises() -> None:+ storage = AsyncBYOC(provider=MemoryProvider("only"))+ with pytest.raises(InvalidInputError):+ await storage.migrate(source="nope", target="only", paths=["a.txt"])+++async def test_migrate_with_no_paths_returns_an_empty_report() -> None:+ storage = AsyncBYOC(providers=[MemoryProvider("a"), MemoryProvider("b")])+ report = await storage.migrate(source="a", target="b", paths=[])+ assert report.files_total == 0+ assert report.results == []diff --git a/python/tests/test_conformance_e2ee.py b/python/tests/test_conformance_e2ee.pynew file mode 100644index 0000000..290f63c--- /dev/null+++ b/python/tests/test_conformance_e2ee.py@@ -0,0 +1,122 @@+"""E2EE conformance: this SDK against the shared cross-SDK envelope vectors.++Passing this suite is what makes a file encrypted by the TypeScript SDK readable+here, and vice versa.+"""++from __future__ import annotations++import time+from typing import Any++import pytest+from conftest import load_fixture++from byoc.encryption import (+ E2EE_MAGIC_HEADER_V2,+ ITER_LENGTH,+ IV_LENGTH,+ MAGIC_LENGTH,+ SALT_LENGTH,+ TAG_LENGTH,+ E2EECrypto,+)+from byoc.errors import ERROR_CLASS_BY_CODE, BYOCErrorCode, StorageError++_FX = load_fixture("e2ee-envelope.json")+_VECTORS: list[dict[str, Any]] = _FX["vectors"]+_REJECTIONS: list[dict[str, Any]] = _FX["rejection_cases"]+_BOUNDS = _FX["iteration_bounds"]+++def _v2_vector() -> dict[str, Any]:+ return next(v for v in _VECTORS if v["version"] == "V2")++[email protected]("vec", _VECTORS, ids=[v["name"] for v in _VECTORS])+def test_derived_key_matches_vector(vec: dict[str, Any]) -> None:+ """Isolates PBKDF2 from AES-GCM, so a mismatch says which half is wrong."""+ crypto = E2EECrypto(passphrase=vec["passphrase"])+ derived = crypto._derive_key(bytes.fromhex(vec["salt_hex"]), vec["iterations"])+ assert derived.hex() == vec["derived_key_hex"]++[email protected]("vec", _VECTORS, ids=[v["name"] for v in _VECTORS])+def test_decrypts_vector(vec: dict[str, Any]) -> None:+ crypto = E2EECrypto(passphrase=vec["passphrase"])+ plaintext = crypto.decrypt_sync(bytes.fromhex(vec["envelope_hex"]))+ assert plaintext.decode("utf-8") == vec["plaintext_utf8"]++[email protected]("vec", _VECTORS, ids=[v["name"] for v in _VECTORS])+def test_envelope_framing_matches_spec(vec: dict[str, Any]) -> None:+ """Correct plaintext with a wrong byte layout would still break the peer SDK."""+ env = bytes.fromhex(vec["envelope_hex"])+ offset = 0++ assert env[offset : offset + MAGIC_LENGTH] == f"BYOC_E2EE_{vec['version']}".encode()+ offset += MAGIC_LENGTH++ if vec["version"] == "V2":+ assert int.from_bytes(env[offset : offset + ITER_LENGTH], "big") == vec["iterations"]+ offset += ITER_LENGTH++ assert env[offset : offset + SALT_LENGTH].hex() == vec["salt_hex"]+ offset += SALT_LENGTH+ assert env[offset : offset + IV_LENGTH].hex() == vec["iv_hex"]+ offset += IV_LENGTH+ assert env[offset : offset + TAG_LENGTH].hex() == vec["tag_hex"]+ offset += TAG_LENGTH+ assert env[offset:].hex() == vec["ciphertext_hex"]+++def test_encrypt_produces_a_spec_conformant_envelope() -> None:+ crypto = E2EECrypto(passphrase="spec-conformance-passphrase")+ envelope = crypto.encrypt_sync("round trip")++ assert envelope[:MAGIC_LENGTH] == E2EE_MAGIC_HEADER_V2+ iterations = int.from_bytes(envelope[MAGIC_LENGTH : MAGIC_LENGTH + ITER_LENGTH], "big")+ assert _BOUNDS["min"] <= iterations <= _BOUNDS["max"]+ assert crypto.decrypt_sync(envelope).decode("utf-8") == "round trip"++[email protected]("case", _REJECTIONS, ids=[c["name"] for c in _REJECTIONS])+def test_rejection_cases(case: dict[str, Any]) -> None:+ vec = _v2_vector()+ env = bytearray(bytes.fromhex(vec["envelope_hex"]))++ mutate = case.get("mutate")+ if mutate:+ offset = mutate["offset"]+ if "uint32_be" in mutate:+ env[offset : offset + 4] = int(mutate["uint32_be"]).to_bytes(4, "big")+ if "ascii" in mutate:+ raw = mutate["ascii"].encode()+ env[offset : offset + len(raw)] = raw++ if case.get("truncate_to") is not None:+ env = env[: case["truncate_to"]]++ crypto = E2EECrypto(passphrase=case.get("passphrase", vec["passphrase"]))+ expected_code = BYOCErrorCode(case["expect_error"])++ started = time.monotonic()+ with pytest.raises(StorageError) as excinfo:+ crypto.decrypt_sync(bytes(env))++ assert excinfo.value.code == expected_code+ assert isinstance(excinfo.value, ERROR_CLASS_BY_CODE[expected_code])+ # An out-of-range work factor must be refused before any key derivation runs.+ assert time.monotonic() - started < 2.0+++async def test_async_api_round_trips() -> None:+ crypto = E2EECrypto(passphrase="async-passphrase")+ envelope = await crypto.encrypt("async payload")+ assert (await crypto.decrypt(envelope)).decode("utf-8") == "async payload"+++def test_rejects_out_of_range_construction() -> None:+ with pytest.raises(StorageError) as excinfo:+ E2EECrypto(passphrase="p", key_derivation_iterations=100)+ assert excinfo.value.code == BYOCErrorCode.INVALID_INPUTdiff --git a/python/tests/test_conformance_paths.py b/python/tests/test_conformance_paths.pynew file mode 100644index 0000000..084fc58--- /dev/null+++ b/python/tests/test_conformance_paths.py@@ -0,0 +1,77 @@+"""Path conformance: this SDK against the shared cross-SDK fixtures."""++from __future__ import annotations++from typing import Any++import pytest+from conftest import load_fixture++from byoc.errors import ERROR_CLASS_BY_CODE, BYOCErrorCode, StorageError+from byoc.paths import (+ encode_path_segments,+ get_basename,+ get_dirname,+ normalize_virtual_path,+ rfc3986_uri_encode,+ split_path,+)++_NORM = load_fixture("path-normalization.json")+_ENC = load_fixture("path-encoding.json")++_NORM_CASES = _NORM["normalize"]["cases"]+_ERR_CASES = _NORM["normalize_errors"]["cases"]+_BASE_CASES = _NORM["basename"]["cases"]+_DIR_CASES = _NORM["dirname"]["cases"]+_SPLIT_CASES = _NORM["split"]["cases"]+_URI_CASES = _ENC["rfc3986_uri_encode"]["cases"]+_SEG_CASES = _ENC["encode_path_segments"]["cases"]+++def _ids(cases: list[dict[str, Any]], key: str = "name") -> list[str]:+ return [str(c.get(key, c.get("input"))) for c in cases]++[email protected]("case", _NORM_CASES, ids=_ids(_NORM_CASES))+def test_normalize(case: dict[str, Any]) -> None:+ raw = case["input"]+ actual = normalize_virtual_path() if raw is None else normalize_virtual_path(raw)+ assert actual == case["expected"]++[email protected]("case", _ERR_CASES, ids=_ids(_ERR_CASES))+def test_normalize_rejects(case: dict[str, Any]) -> None:+ expected_code = BYOCErrorCode(case["error_code"])+ expected_cls = ERROR_CLASS_BY_CODE[expected_code]++ with pytest.raises(StorageError) as excinfo:+ normalize_virtual_path(case["input"])++ assert excinfo.value.code == expected_code+ assert isinstance(excinfo.value, expected_cls)++[email protected]("case", _BASE_CASES, ids=_ids(_BASE_CASES, "input"))+def test_basename(case: dict[str, Any]) -> None:+ assert get_basename(case["input"]) == case["expected"]++[email protected]("case", _DIR_CASES, ids=_ids(_DIR_CASES, "input"))+def test_dirname(case: dict[str, Any]) -> None:+ assert get_dirname(case["input"]) == case["expected"]++[email protected]("case", _SPLIT_CASES, ids=_ids(_SPLIT_CASES, "input"))+def test_split(case: dict[str, Any]) -> None:+ assert split_path(case["input"]) == case["expected"]++[email protected]("case", _URI_CASES, ids=_ids(_URI_CASES, "input"))+def test_rfc3986_uri_encode(case: dict[str, Any]) -> None:+ assert rfc3986_uri_encode(case["input"], case["encode_slash"]) == case["expected"]++[email protected]("case", _SEG_CASES, ids=_ids(_SEG_CASES, "input"))+def test_encode_path_segments(case: dict[str, Any]) -> None:+ assert encode_path_segments(case["input"]) == case["expected"]diff --git a/python/tests/test_conformance_pkce.py b/python/tests/test_conformance_pkce.pynew file mode 100644index 0000000..dc0c460--- /dev/null+++ b/python/tests/test_conformance_pkce.py@@ -0,0 +1,72 @@+"""PKCE conformance against the shared vectors.++The first vector is RFC 7636 Appendix B, so this is an external check rather+than a snapshot of our own output. A mismatch means Google rejects one SDK's+OAuth flow while accepting the other's.+"""++from __future__ import annotations++import re+from typing import Any++import pytest+from conftest import load_fixture++from byoc.providers.gdrive import (+ generate_code_challenge,+ generate_code_verifier,+ generate_oauth_state,+)++_FX = load_fixture("pkce.json")+_CASES: list[dict[str, Any]] = _FX["cases"]+_RULES = _FX["verifier_rules"]++_UNRESERVED = re.compile(r"^[A-Za-z0-9\-._~]+$")+++def test_rfc7636_appendix_b_vector() -> None:+ """The canonical published vector, checked explicitly."""+ vector = _FX["rfc7636_appendix_b"]+ assert generate_code_challenge(vector["code_verifier"]) == vector["code_challenge"]++[email protected]("case", _CASES, ids=[c["code_verifier"][:24] for c in _CASES])+def test_code_challenge_matches_vector(case: dict[str, Any]) -> None:+ assert generate_code_challenge(case["code_verifier"]) == case["code_challenge"]++[email protected]("case", _CASES, ids=[c["code_verifier"][:24] for c in _CASES])+def test_challenge_is_unpadded_base64url(case: dict[str, Any]) -> None:+ """base64url with '=' padding, '+' or '/' would be rejected by Google."""+ challenge = generate_code_challenge(case["code_verifier"])+ assert "=" not in challenge+ assert "+" not in challenge+ assert "/" not in challenge+ assert len(challenge) == 43 # SHA-256 is 32 bytes -> 43 base64url chars++[email protected]("length", [43, 64, 100, 128])+def test_generated_verifiers_satisfy_the_rules(length: int) -> None:+ verifier = generate_code_verifier(length)+ assert len(verifier) == length+ assert _RULES["min_length"] <= len(verifier) <= _RULES["max_length"]+ assert _UNRESERVED.match(verifier)++[email protected](("requested", "expected"), [(1, 43), (10, 43), (500, 128)])+def test_verifier_length_is_clamped_to_the_rfc_range(requested: int, expected: int) -> None:+ assert len(generate_code_verifier(requested)) == expected+++def test_verifiers_are_unpredictable() -> None:+ """A predictable verifier defeats the point of PKCE entirely."""+ generated = {generate_code_verifier(64) for _ in range(200)}+ assert len(generated) == 200+++def test_oauth_state_is_random_and_sized() -> None:+ states = {generate_oauth_state(32) for _ in range(200)}+ assert len(states) == 200+ assert all(len(s) == 32 for s in states)diff --git a/python/tests/test_conformance_sigv4.py b/python/tests/test_conformance_sigv4.pynew file mode 100644index 0000000..60781e4--- /dev/null+++ b/python/tests/test_conformance_sigv4.py@@ -0,0 +1,100 @@+"""SigV4 conformance: this SDK against the shared cross-SDK vectors.++If these pass, the Python adapter can authenticate to the same S3/R2/MinIO+endpoints the TypeScript adapter can.+"""++from __future__ import annotations++import re+from datetime import datetime+from typing import Any+from urllib.parse import urlsplit++import pytest+from conftest import load_fixture++from byoc.providers._sigv4 import (+ EMPTY_BODY_SHA256,+ build_canonical_query_string,+ create_presigned_s3_url,+ sign_s3_request,+)++_FX = load_fixture("sigv4.json")+_CRED = _FX["credentials"]+_MOMENT = datetime.fromisoformat(_FX["datetime_iso"].replace("Z", "+00:00"))+_QUERY_CASES: list[dict[str, Any]] = _FX["canonical_query"]+_VECTORS: list[dict[str, Any]] = _FX["vectors"]+_PRESIGNED: list[dict[str, Any]] = _FX["presigned"]+++def test_empty_body_hash_matches_spec() -> None:+ assert _FX["empty_body_sha256"] == EMPTY_BODY_SHA256++[email protected]("case", _QUERY_CASES, ids=[c["url"] for c in _QUERY_CASES])+def test_canonical_query_string(case: dict[str, Any]) -> None:+ query = urlsplit(case["url"]).query+ assert build_canonical_query_string(query) == case["expected"]++[email protected]("vec", _VECTORS, ids=[v["name"] for v in _VECTORS])+def test_signature_matches_vector(vec: dict[str, Any]) -> None:+ body = vec["body"].encode("utf-8") if vec["body"] is not None else None+ signed = sign_s3_request(+ access_key_id=_CRED["access_key_id"],+ secret_access_key=_CRED["secret_access_key"],+ region=_CRED["region"],+ service=_CRED["service"],+ method=vec["method"],+ url=vec["url"],+ headers=vec["headers"],+ body=body,+ moment=_MOMENT,+ )++ assert signed["Authorization"] == vec["authorization"]++ match = re.search(r"Signature=([0-9a-f]+)", signed["Authorization"])+ assert match is not None+ assert match.group(1) == vec["signature"]++ signed_headers = re.search(r"SignedHeaders=([^,]+)", signed["Authorization"])+ assert signed_headers is not None+ assert signed_headers.group(1) == vec["signed_headers"]+++def test_header_casing_does_not_change_the_signature() -> None:+ """A caller passing 'Content-Type' must sign identically to 'content-type'."""+ common = {+ "access_key_id": _CRED["access_key_id"],+ "secret_access_key": _CRED["secret_access_key"],+ "region": _CRED["region"],+ "method": "PUT",+ "url": "https://examplebucket.s3.amazonaws.com/k.txt",+ "body": b"x",+ "moment": _MOMENT,+ }+ upper = sign_s3_request(**common, headers={"Content-Type": "text/plain"}) # type: ignore[arg-type]+ lower = sign_s3_request(**common, headers={"content-type": "text/plain"}) # type: ignore[arg-type]++ assert upper["Authorization"] == lower["Authorization"]+ # The header must also go on the wire in the form that was signed.+ assert "content-type" in upper+ assert "Content-Type" not in upper++[email protected]("case", _PRESIGNED, ids=[c["name"] for c in _PRESIGNED])+def test_presigned_url_matches_vector(case: dict[str, Any]) -> None:+ url = create_presigned_s3_url(+ access_key_id=_CRED["access_key_id"],+ secret_access_key=_CRED["secret_access_key"],+ region=_CRED["region"],+ service=_CRED["service"],+ url=case["url"],+ method=case["method"],+ expires_in_seconds=case["expires_in_seconds"],+ moment=_MOMENT,+ )+ assert url == case["expected_url"]diff --git a/python/tests/test_gdrive.py b/python/tests/test_gdrive.pynew file mode 100644index 0000000..0a59f41--- /dev/null+++ b/python/tests/test_gdrive.py@@ -0,0 +1,472 @@+"""Google Drive adapter tests over a mock HTTP transport.++Drive cannot be exercised in CI -- it needs a real Google account and a browser+consent step -- so these cover as much of the wire behaviour as possible without+one: query escaping, the appProperties contract, OAuth refresh, resumable+chunking, error mapping, and cache self-healing.+"""++from __future__ import annotations++import json+import time+from pathlib import Path+from typing import Any+from urllib.parse import parse_qs, urlparse++import httpx+import pytest++from byoc.errors import (+ AuthRequiredError,+ ObjectNotFoundError,+ QuotaExceededError,+ RateLimitedError,+ TokenExpiredError,+)+from byoc.providers.gdrive import (+ VIRTUAL_PATH_PROPERTY,+ EncryptedFileTokenStorage,+ GoogleDriveProvider,+ GoogleDriveScope,+ GoogleOAuthClient,+ InMemoryTokenStorage,+ LruTtlPathCache,+ TokenSession,+ escape_drive_query_value,+)++FOLDER_MIME = "application/vnd.google-apps.folder"+++# -- query escaping ----------------------------------------------------------+++ ("raw", "escaped"),+ [+ ("simple.txt", "simple.txt"),+ ("Bob's Notes.pdf", "Bob\\'s Notes.pdf"),+ ("back\\slash.txt", "back\\\\slash.txt"),+ ("both'and\\.txt", "both\\'and\\\\.txt"),+ ("x' or name != '", "x\\' or name != \\'"),+ ],+)+def test_drive_query_escaping(raw: str, escaped: str) -> None:+ """An unescaped quote breaks the query, or injects extra clauses into it."""+ assert escape_drive_query_value(raw) == escaped+++def test_backslashes_are_escaped_before_quotes() -> None:+ """Wrong order double-escapes the backslash added for the quote."""+ assert escape_drive_query_value("a\\'b") == "a\\\\\\'b"+++# -- path cache --------------------------------------------------------------+++def test_cache_expires_entries() -> None:+ cache = LruTtlPathCache(ttl_seconds=0.0)+ cache.set("a/b.txt", "id-1")+ assert cache.get("a/b.txt") is None+++def test_cache_evicts_least_recently_used() -> None:+ cache = LruTtlPathCache(max_entries=2)+ cache.set("a", "1")+ cache.set("b", "2")+ cache.get("a") # make "b" the least recently used+ cache.set("c", "3")++ assert cache.get("a") == "1"+ assert cache.get("b") is None+ assert cache.get("c") == "3"+++def test_invalidate_drops_descendants() -> None:+ """A moved folder makes every cached path beneath it suspect."""+ cache = LruTtlPathCache()+ cache.set("a", "1")+ cache.set("a/b", "2")+ cache.set("a/b/c.txt", "3")+ cache.set("other", "4")++ cache.invalidate("a")++ assert cache.get("a") is None+ assert cache.get("a/b") is None+ assert cache.get("a/b/c.txt") is None+ assert cache.get("other") == "4"+++# -- OAuth -------------------------------------------------------------------+++def test_authorization_url_contains_pkce_and_offline_access() -> None:+ oauth = GoogleOAuthClient(client_id="cid", redirect_uri="https://app.example/cb")+ url = oauth.get_authorization_url(state="st8", code_challenge="chal")+ params = parse_qs(urlparse(url).query)++ assert params["client_id"] == ["cid"]+ assert params["code_challenge"] == ["chal"]+ assert params["code_challenge_method"] == ["S256"]+ assert params["state"] == ["st8"]+ # Without offline+consent Google never returns a refresh token.+ assert params["access_type"] == ["offline"]+ assert params["prompt"] == ["consent"]+ assert params["scope"] == [GoogleDriveScope.FILE]+++def test_authorization_url_requires_a_redirect_uri() -> None:+ from byoc.errors import InvalidInputError++ oauth = GoogleOAuthClient(client_id="cid")+ with pytest.raises(InvalidInputError):+ oauth.get_authorization_url()+++async def test_exchange_code_stores_the_session() -> None:+ captured: dict[str, Any] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ captured["form"] = parse_qs(request.content.decode())+ return httpx.Response(+ 200,+ json={+ "access_token": "at-1",+ "refresh_token": "rt-1",+ "expires_in": 3599,+ "token_type": "Bearer",+ "scope": GoogleDriveScope.FILE,+ },+ )++ storage = InMemoryTokenStorage()+ oauth = GoogleOAuthClient(+ client_id="cid",+ redirect_uri="https://app.example/cb",+ token_storage=storage,+ client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),+ )++ session = await oauth.exchange_code(code="auth-code", code_verifier="verifier")++ assert captured["form"]["code_verifier"] == ["verifier"]+ assert captured["form"]["grant_type"] == ["authorization_code"]+ assert session.access_token == "at-1"+ assert storage.get() is not None+++async def test_refresh_preserves_the_refresh_token() -> None:+ """Google omits refresh_token on refresh; dropping it would end the session."""++ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(200, json={"access_token": "at-2", "expires_in": 3599})++ storage = InMemoryTokenStorage(+ TokenSession(access_token="old", refresh_token="rt-keep", expires_at=time.time() - 10)+ )+ oauth = GoogleOAuthClient(+ client_id="cid",+ token_storage=storage,+ client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),+ )++ token = await oauth.get_access_token()+ assert token == "at-2"++ stored = storage.get()+ assert stored is not None+ assert stored.refresh_token == "rt-keep"+++async def test_expired_session_without_refresh_token_raises() -> None:+ oauth = GoogleOAuthClient(+ client_id="cid",+ token_storage=InMemoryTokenStorage(+ TokenSession(access_token="old", expires_at=time.time() - 10)+ ),+ client=httpx.AsyncClient(transport=httpx.MockTransport(lambda r: httpx.Response(200))),+ )+ with pytest.raises(AuthRequiredError):+ await oauth.get_access_token()+++async def test_invalid_grant_maps_to_token_expired() -> None:+ """A dead refresh token needs re-consent, not a retry."""++ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(400, json={"error": "invalid_grant", "error_description": "expired"})++ oauth = GoogleOAuthClient(+ client_id="cid",+ token_storage=InMemoryTokenStorage(+ TokenSession(access_token="a", refresh_token="dead", expires_at=time.time() - 10)+ ),+ client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),+ )+ with pytest.raises(TokenExpiredError):+ await oauth.get_access_token()+++async def test_revoke_clears_storage_even_when_the_call_fails() -> None:+ """A revoked token must never linger locally."""++ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(500, text="boom")++ storage = InMemoryTokenStorage(TokenSession(access_token="a", refresh_token="r"))+ oauth = GoogleOAuthClient(+ client_id="cid",+ token_storage=storage,+ client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),+ )+ await oauth.revoke()+ assert storage.get() is None+++# -- token storage -----------------------------------------------------------+++def test_encrypted_file_storage_roundtrip(tmp_path: Path) -> None:+ target = tmp_path / "session.enc"+ storage = EncryptedFileTokenStorage(target, "a-strong-encryption-key")++ storage.set(TokenSession(access_token="at", refresh_token="rt", expires_at=123.0))+ loaded = storage.get()++ assert loaded is not None+ assert loaded.refresh_token == "rt"+ # The refresh token must not be readable on disk.+ assert b"rt" not in target.read_bytes()+ assert target.read_bytes()[:12] == b"BYOC_E2EE_V2"+++def test_encrypted_file_storage_is_owner_only(tmp_path: Path) -> None:+ target = tmp_path / "session.enc"+ EncryptedFileTokenStorage(target, "key").set(TokenSession(access_token="at"))+ assert oct(target.stat().st_mode)[-3:] == "600"+++def test_encrypted_file_storage_survives_a_wrong_key(tmp_path: Path) -> None:+ """A foreign or corrupt file means 're-authenticate', not a crash."""+ target = tmp_path / "session.enc"+ EncryptedFileTokenStorage(target, "key-a").set(TokenSession(access_token="at"))+ assert EncryptedFileTokenStorage(target, "key-b").get() is None+++def test_session_expiry_uses_a_safety_margin() -> None:+ """A token expiring in 10s is treated as expired, not used and lost mid-call."""+ assert TokenSession(access_token="a", expires_at=time.time() + 10).is_expired is True+ assert TokenSession(access_token="a", expires_at=time.time() + 600).is_expired is False+ assert TokenSession(access_token="a").is_expired is False+++# -- adapter -----------------------------------------------------------------+++class FakeDrive:+ """A small in-memory stand-in for the Drive API."""++ def __init__(self) -> None:+ self.files: dict[str, dict[str, Any]] = {}+ self.content: dict[str, bytes] = {}+ self.queries: list[str] = []+ self._next_id = 0+ self.root_id = self._add("BYOC", FOLDER_MIME, "root")++ def _add(self, name: str, mime: str, parent: str, **extra: Any) -> str:+ self._next_id += 1+ file_id = f"id-{self._next_id}"+ self.files[file_id] = {"id": file_id, "name": name, "mimeType": mime,+ "parents": [parent], "trashed": False, **extra}+ return file_id++ def handler(self, request: httpx.Request) -> httpx.Response:+ url = str(request.url)++ if "oauth2.googleapis.com" in url:+ return httpx.Response(200, json={"access_token": "at", "expires_in": 3599})++ if request.method == "GET" and "/files" in url and "alt=media" in url:+ file_id = url.split("/files/")[1].split("?")[0]+ return httpx.Response(200, content=self.content.get(file_id, b""))++ if (request.method == "GET" and url.rstrip("/").endswith("/about")) or "/about?" in url:+ return httpx.Response(+ 200, json={"storageQuota": {"usage": "1024", "limit": "15000000000"}}+ )++ if request.method == "GET" and "/files?" in url:+ query = parse_qs(urlparse(url).query).get("q", [""])[0]+ self.queries.append(query)+ return httpx.Response(200, json={"files": self._match(query)})++ if request.method == "GET" and "/files/" in url:+ file_id = url.split("/files/")[1].split("?")[0]+ if file_id not in self.files:+ return httpx.Response(404, json={"error": {"message": "Not found"}})+ return httpx.Response(200, json=self.files[file_id])++ if request.method == "POST" and "upload/drive" in url:+ body = request.content+ parts = body.split(b"\r\n\r\n")+ meta = json.loads(parts[1].split(b"\r\n--")[0])+ content = parts[2].rsplit(b"\r\n--", 1)[0] if len(parts) > 2 else b""+ file_id = self._add(+ meta["name"], meta.get("mimeType", ""), meta["parents"][0],+ appProperties=meta.get("appProperties", {}), size=str(len(content)),+ )+ self.content[file_id] = content+ return httpx.Response(200, json=self.files[file_id])++ if request.method == "POST" and "/files" in url:+ meta = json.loads(request.content)+ file_id = self._add(meta["name"], meta["mimeType"], meta["parents"][0])+ return httpx.Response(200, json={"id": file_id})++ if request.method == "DELETE":+ file_id = url.split("/files/")[1].split("?")[0]+ self.files.pop(file_id, None)+ return httpx.Response(204)++ return httpx.Response(404, json={"error": {"message": f"unhandled {request.method} {url}"}})++ def _match(self, query: str) -> list[dict[str, Any]]:+ results = []+ for record in self.files.values():+ if record["trashed"]:+ continue+ name = record["name"].replace("\\", "\\\\").replace("'", "\\'")+ if f"name = '{name}'" not in query:+ continue+ parent = record["parents"][0]+ if f"'{parent}' in parents" not in query:+ continue+ if FOLDER_MIME in query and record["mimeType"] != FOLDER_MIME:+ continue+ results.append(record)+ return results+++def _provider(drive: FakeDrive, **kwargs: Any) -> GoogleDriveProvider:+ return GoogleDriveProvider(+ client_id="cid",+ session=TokenSession(access_token="at", refresh_token="rt", expires_at=time.time() + 3600),+ client=httpx.AsyncClient(transport=httpx.MockTransport(drive.handler)),+ **kwargs,+ )+++def test_manifest_and_capabilities() -> None:+ provider = _provider(FakeDrive())+ assert provider.manifest().id == "google-drive"+ assert provider.manifest().category == "personal-cloud"+ caps = provider.capabilities()+ assert caps.folders is True+ assert caps.quota is True+ assert caps.resumable_uploads is True+++async def test_upload_writes_the_shared_virtual_path_property() -> None:+ """byocVirtualPath is wire format: the TypeScript SDK reads this exact key."""+ drive = FakeDrive()+ provider = _provider(drive)++ obj = await provider.upload("docs/report.pdf", b"PDF", None)++ record = drive.files[obj.provider_id]+ assert record["appProperties"][VIRTUAL_PATH_PROPERTY] == "docs/report.pdf"+ assert obj.path == "docs/report.pdf"+ assert obj.name == "report.pdf"+++async def test_upload_creates_nested_folders() -> None:+ drive = FakeDrive()+ provider = _provider(drive)+ await provider.upload("a/b/c/deep.txt", b"x", None)++ folder_names = [f["name"] for f in drive.files.values() if f["mimeType"] == FOLDER_MIME]+ assert {"BYOC", "a", "b", "c"} <= set(folder_names)+++async def test_apostrophe_filenames_are_escaped_in_queries() -> None:+ """The bug that once made every apostrophe filename a 400."""+ drive = FakeDrive()+ provider = _provider(drive)++ await provider.upload("notes/Bob's Notes.pdf", b"x", None)+ # Clear the cache so the lookup actually reaches Drive.+ provider.resolver.cache.clear()+ assert await provider.exists("notes/Bob's Notes.pdf") is True+ assert any("Bob\\'s Notes.pdf" in q for q in drive.queries)+++async def test_download_roundtrip() -> None:+ drive = FakeDrive()+ provider = _provider(drive)+ await provider.upload("docs/note.txt", b"hello drive", None)++ out = await provider.download("docs/note.txt")+ assert await out.read() == b"hello drive"+++async def test_missing_file_raises_not_found() -> None:+ provider = _provider(FakeDrive())+ with pytest.raises(ObjectNotFoundError):+ await provider.metadata("docs/absent.txt")+++async def test_delete_is_idempotent() -> None:+ drive = FakeDrive()+ provider = _provider(drive)+ await provider.upload("temp.txt", b"x", None)++ await provider.delete("temp.txt")+ assert await provider.exists("temp.txt") is False+ await provider.delete("temp.txt") # must not raise+++async def test_self_heals_after_an_out_of_band_delete() -> None:+ """A user deleting a file in the Drive UI leaves a stale cached id behind."""+ drive = FakeDrive()+ provider = _provider(drive)+ obj = await provider.upload("docs/a.txt", b"x", None)++ # Simulate the web UI: the file vanishes, but our cache still points at it.+ del drive.files[obj.provider_id]+ assert provider.resolver.cache.get("docs/a.txt") is not None++ assert await provider.exists("docs/a.txt") is False+ assert provider.resolver.cache.get("docs/a.txt") is None+++async def test_quota_is_reported() -> None:+ provider = _provider(FakeDrive())+ quota = await provider.quota()+ assert quota.used == 1024+ assert quota.total == 15_000_000_000+ assert quota.available == 15_000_000_000 - 1024+++# -- error mapping -----------------------------------------------------------+++ ("status", "reason", "expected"),+ [+ (403, "storageQuotaExceeded", QuotaExceededError),+ (403, "rateLimitExceeded", RateLimitedError),+ (429, "", RateLimitedError),+ (401, "", AuthRequiredError),+ (404, "", ObjectNotFoundError),+ ],+)+def test_drive_error_mapping(status: int, reason: str, expected: type) -> None:+ """403 is overloaded by Drive: quota and rate limits hide behind it."""+ from byoc.providers.gdrive._http import DriveHttpClient++ payload = {"error": {"message": "m", "errors": [{"reason": reason}] if reason else []}}+ response = httpx.Response(status, json=payload)+ mapped = DriveHttpClient(lambda: "token").map_error(response)+ assert isinstance(mapped, expected)diff --git a/python/tests/test_s3_adapter.py b/python/tests/test_s3_adapter.pynew file mode 100644index 0000000..56d9d0d--- /dev/null+++ b/python/tests/test_s3_adapter.py@@ -0,0 +1,224 @@+"""S3 adapter unit tests driven through a mock HTTP transport.++These assert what goes on the wire -- URL shape, signed headers, error mapping,+pagination -- without needing a server. The MinIO integration suite covers the+half these cannot: that a real S3 implementation accepts them.+"""++from __future__ import annotations++import httpx+import pytest++from byoc.errors import (+ InvalidInputError,+ ObjectNotFoundError,+ PermissionDeniedError,+ StorageError,+)+from byoc.providers.s3 import S3CompatibleProvider++_LIST_XML_PAGE_1 = """<?xml version="1.0" encoding="UTF-8"?>+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">+ <IsTruncated>true</IsTruncated>+ <NextContinuationToken>TOKEN-2</NextContinuationToken>+ <CommonPrefixes><Prefix>docs/reports/</Prefix></CommonPrefixes>+ <Contents>+ <Key>docs/a.txt</Key><Size>11</Size>+ <ETag>"abc123"</ETag><LastModified>2026-08-25T00:00:00.000Z</LastModified>+ </Contents>+</ListBucketResult>"""++_LIST_XML_PAGE_2 = """<?xml version="1.0" encoding="UTF-8"?>+<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">+ <IsTruncated>false</IsTruncated>+ <Contents>+ <Key>docs/b.txt</Key><Size>22</Size>+ </Contents>+</ListBucketResult>"""+++def _provider(handler: object, **kwargs: object) -> S3CompatibleProvider:+ transport = httpx.MockTransport(handler) # type: ignore[arg-type]+ defaults: dict[str, object] = {+ "endpoint": "https://acct.r2.cloudflarestorage.com",+ "bucket": "user-assets",+ "region": "auto",+ "access_key_id": "AKIDEXAMPLE",+ "secret_access_key": "secret",+ "client": httpx.AsyncClient(transport=transport),+ }+ defaults.update(kwargs)+ return S3CompatibleProvider(**defaults) # type: ignore[arg-type]+++def test_requires_credentials() -> None:+ with pytest.raises(InvalidInputError):+ S3CompatibleProvider(+ endpoint="", bucket="", region="auto", access_key_id="", secret_access_key=""+ )+++def test_manifest_and_capabilities() -> None:+ provider = _provider(lambda request: httpx.Response(200))+ assert provider.manifest().id == "s3-compatible"+ assert provider.manifest().category == "developer-cloud"+ caps = provider.capabilities()+ # S3 has no native folders or account quota; those must not be faked.+ assert caps.folders is False+ assert caps.quota is False+ assert caps.public_urls is True+++async def test_upload_signs_and_encodes_the_key() -> None:+ seen: dict[str, object] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ seen["url"] = str(request.url)+ seen["auth"] = request.headers.get("authorization")+ seen["ctype"] = request.headers.get("content-type")+ return httpx.Response(200, headers={"etag": '"deadbeef"'})++ provider = _provider(handler, root_prefix="production/data")+ obj = await provider.upload("users/123/avatar.png", b"PNG", None)++ assert seen["url"] == (+ "https://acct.r2.cloudflarestorage.com/production/data/users/123/avatar.png"+ )+ assert str(seen["auth"]).startswith("AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/")+ assert obj.checksum == "deadbeef"+ assert obj.provider_id == "production/data/users/123/avatar.png"+++ ("filename", "encoded"),+ [+ ("notes/draft#2.pdf", "notes/draft%232.pdf"),+ ("notes/what?.txt", "notes/what%3F.txt"),+ ("Q3 report.pdf", "Q3%20report.pdf"),+ ("docs/café.txt", "docs/caf%C3%A9.txt"),+ ],+)+async def test_object_keys_survive_url_encoding(filename: str, encoded: str) -> None:+ """A '#' or '?' left unencoded silently truncates the key and loses data."""+ seen: dict[str, str] = {}++ def handler(request: httpx.Request) -> httpx.Response:+ seen["url"] = str(request.url)+ return httpx.Response(200, headers={"etag": '"x"'})++ provider = _provider(handler)+ await provider.upload(filename, b"data", None)+ assert seen["url"] == f"https://acct.r2.cloudflarestorage.com/{encoded}"+++async def test_download_returns_bytes_and_metadata() -> None:+ def handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(+ 200,+ content=b"Hello S3",+ headers={"content-type": "text/plain", "content-length": "8", "etag": '"e1"'},+ )++ provider = _provider(handler)+ out = await provider.download("notes.txt")+ assert await out.read() == b"Hello S3"+ assert await out.text() == "Hello S3"+ assert out.metadata.mime_type == "text/plain"+ assert out.metadata.size == 8+ assert out.metadata.checksum == "e1"+++async def test_download_maps_404_to_object_not_found() -> None:+ provider = _provider(+ lambda request: httpx.Response(404, text="<Error><Code>NoSuchKey</Code></Error>")+ )+ with pytest.raises(ObjectNotFoundError) as excinfo:+ await provider.download("missing.txt")+ assert excinfo.value.code == "BYOC_OBJECT_NOT_FOUND"+++async def test_maps_403_to_permission_denied() -> None:+ provider = _provider(+ lambda request: httpx.Response(403, text="<Error><Code>AccessDenied</Code></Error>")+ )+ with pytest.raises(PermissionDeniedError):+ await provider.download("secret.txt")+++async def test_delete_treats_missing_object_as_success() -> None:+ """S3 delete is idempotent; a 404 must not surface as an error."""+ provider = _provider(lambda request: httpx.Response(404, text="NoSuchKey"))+ await provider.delete("already-gone.txt")+++async def test_exists_returns_false_without_raising() -> None:+ provider = _provider(lambda request: httpx.Response(404))+ assert await provider.exists("nope.txt") is False+++async def test_list_follows_pagination() -> None:+ """Object 1001 must not vanish: ListObjectsV2 caps each page at 1000 keys."""+ calls: list[str] = []++ def handler(request: httpx.Request) -> httpx.Response:+ calls.append(str(request.url))+ token = request.url.params.get("continuation-token")+ return httpx.Response(200, text=_LIST_XML_PAGE_2 if token else _LIST_XML_PAGE_1)++ provider = _provider(handler)+ objects = await provider.list("docs")++ assert len(calls) == 2+ assert "continuation-token=TOKEN-2" in calls[1]++ paths = [o.path for o in objects]+ assert paths == ["docs/reports", "docs/a.txt", "docs/b.txt"]+ assert objects[0].type == "folder"+ assert objects[1].type == "file"+ assert objects[1].size == 11+ assert objects[1].checksum == "abc123"+++async def test_retries_transient_5xx_then_succeeds() -> None:+ attempts = {"n": 0}++ def handler(request: httpx.Request) -> httpx.Response:+ attempts["n"] += 1+ if attempts["n"] < 3:+ return httpx.Response(503, text="SlowDown")+ return httpx.Response(200, content=b"ok", headers={"content-type": "text/plain"})++ provider = _provider(handler)+ out = await provider.download("flaky.txt")+ assert await out.read() == b"ok"+ assert attempts["n"] == 3+++async def test_does_not_retry_a_non_retryable_error() -> None:+ """Retrying a 403 burns attempts on something that cannot succeed."""+ attempts = {"n": 0}++ def handler(request: httpx.Request) -> httpx.Response:+ attempts["n"] += 1+ return httpx.Response(403, text="AccessDenied")++ provider = _provider(handler)+ with pytest.raises(StorageError):+ await provider.download("denied.txt")+ assert attempts["n"] == 1+++def test_presigned_url_is_query_authenticated() -> None:+ provider = _provider(lambda request: httpx.Response(200))+ url = provider.presigned_url("notes/draft#2.pdf", expires_in_seconds=900)+ assert "X-Amz-Algorithm=AWS4-HMAC-SHA256" in url+ assert "X-Amz-Expires=900" in url+ assert "X-Amz-Signature=" in url+ assert "draft%232.pdf" in url+++def test_force_path_style_puts_bucket_in_the_path() -> None:+ """MinIO and most self-hosted gateways require path-style addressing."""+ provider = _provider(lambda request: httpx.Response(200), force_path_style=True)+ assert provider.object_url("a/b.txt").endswith("/user-assets/a/b.txt")diff --git a/spec/README.md b/spec/README.mdnew file mode 100644index 0000000..aea5bee--- /dev/null+++ b/spec/README.md@@ -0,0 +1,43 @@+# BYOC Conformance Fixtures++Language-neutral test vectors shared by every BYOC SDK implementation.++BYOC is not a wire protocol. Two SDKs never talk to each other, they both talk to Google Drive, S3, or WebDAV. So these fixtures cover exactly the surfaces where independent implementations write to **shared external state**, and where drift means a file written by one SDK cannot be read by another.++Everything else (method names, error class hierarchies, sync vs async) is API design, and should be idiomatic per language. It is deliberately **not** specified here.++## The fixtures++| File | Covers | Why it matters |+| :--- | :--- | :--- |+| `path-normalization.json` | `normalizeVirtualPath`, `getBasename`, `getDirname`, `splitPath` | Decides which folder bytes land in |+| `path-encoding.json` | `rfc3986UriEncode`, `encodePathSegments` | Decides the actual S3 key / WebDAV URL |+| `e2ee-envelope.json` | AES-256-GCM envelope byte layout | A one-byte disagreement makes encrypted files permanently unreadable |+| `provider-metadata.json` | `byocVirtualPath` and `x-amz-meta-*` key names | Wire format, not API surface; must stay camelCase in every language |++## Rules++1. **Fixtures are the contract.** If an implementation disagrees with a fixture, fix the implementation, not the fixture.+2. **Changing an expectation is a breaking change.** It means previously written files may no longer be readable. Bump the envelope version (`BYOC_E2EE_V2` → `V3`) rather than redefining an existing one.+3. **Error codes are shared; error *types* are not.** A fixture saying `BYOC_INVALID_INPUT` means TypeScript throws `StorageError` with that `code` and Python raises its equivalent exception. The string is the contract.+4. **Add a case whenever a bug is found.** Every vector in `path-encoding.json` marked `note` exists because that exact input once broke something.++## Running them++**TypeScript**: [`packages/core/tests/spec/conformance.test.ts`](../packages/core/tests/spec/conformance.test.ts):++```bash+npx vitest run packages/core/tests/spec/conformance.test.ts+```++**Python**: planned for `python/tests/test_conformance.py`, loading the same JSON from this directory.++## Regenerating the E2EE vectors++The envelope vectors are generated with fixed salt/IV so they are byte-reproducible. They should only be regenerated when the envelope format itself changes, and that requires a new version header, not an in-place edit.++## What is deliberately not here++- **AWS SigV4 vectors.** AWS publishes its own; both SDKs should test against those rather than a fork of someone else's truth.+- **Capability matrices and method signatures.** API ergonomics, not interop.+- **A prose specification.** These four files plus this README are the spec. A longer document can follow once two implementations disagree about something real.diff --git a/spec/fixtures/e2ee-envelope.json b/spec/fixtures/e2ee-envelope.jsonnew file mode 100644index 0000000..aafd39d--- /dev/null+++ b/spec/fixtures/e2ee-envelope.json@@ -0,0 +1,116 @@+{+ "$comment": "BYOC E2EE envelope conformance vectors. The envelope is a binary format written into the user's cloud; a one-byte disagreement between SDKs makes encrypted files permanently unreadable. Algorithm: AES-256-GCM, key = PBKDF2-HMAC-SHA256(passphrase, salt, iterations, dkLen=32). The magic header, iteration field and salt are bound as GCM AAD. All hex is lowercase.",+ "version": 1,+ "algorithm": {+ "cipher": "AES-256-GCM",+ "kdf": "PBKDF2-HMAC-SHA256",+ "key_length_bytes": 32,+ "salt_length_bytes": 16,+ "iv_length_bytes": 12,+ "tag_length_bytes": 16,+ "iter_field_length_bytes": 4,+ "iter_field_encoding": "uint32 big-endian"+ },+ "iteration_bounds": {+ "min": 10000,+ "max": 2000000,+ "$comment": "Read from untrusted storage before the GCM tag can authenticate it, so it MUST be range-checked before key derivation. Out-of-range MUST raise BYOC_CORRUPTED_DATA without deriving a key."+ },+ "layouts": {+ "V2": [+ "MAGIC(12)",+ "ITER(4)",+ "SALT(16)",+ "IV(12)",+ "TAG(16)",+ "CIPHERTEXT(n)"+ ],+ "V1": [+ "MAGIC(12)",+ "SALT(16)",+ "IV(12)",+ "TAG(16)",+ "CIPHERTEXT(n)"+ ]+ },+ "aad": {+ "V2": "MAGIC || ITER || SALT",+ "V1": "MAGIC || SALT"+ },+ "vectors": [+ {+ "name": "V2 envelope, 600000 iterations",+ "version": "V2",+ "magic": "BYOC_E2EE_V2",+ "passphrase": "correct-horse-battery-staple",+ "iterations": 600000,+ "salt_hex": "000102030405060708090a0b0c0d0e0f",+ "iv_hex": "101112131415161718191a1b",+ "plaintext_utf8": "BYOC cross-SDK conformance payload",+ "derived_key_hex": "bd012c265e9e3c0931ca12018be26efe1b5d6355bc3c72acf8dbc0cb811a0107",+ "tag_hex": "916a930f1fa3634ddd740310628ab2e7",+ "ciphertext_hex": "d3b86f9e5c9d265790d4049ac15aee6e56e10d3494037e323a72e340c845b4b8a26d",+ "envelope_hex": "42594f435f453245455f5632000927c0000102030405060708090a0b0c0d0e0f101112131415161718191a1b916a930f1fa3634ddd740310628ab2e7d3b86f9e5c9d265790d4049ac15aee6e56e10d3494037e323a72e340c845b4b8a26d"+ },+ {+ "name": "V1 legacy envelope, 100000 iterations (no ITER field)",+ "version": "V1",+ "magic": "BYOC_E2EE_V1",+ "passphrase": "correct-horse-battery-staple",+ "iterations": 100000,+ "salt_hex": "000102030405060708090a0b0c0d0e0f",+ "iv_hex": "101112131415161718191a1b",+ "plaintext_utf8": "BYOC cross-SDK conformance payload",+ "derived_key_hex": "074ca47d1f67efe76642863fb039d88757c2b8d95f526ea9715a38f5bb48be1f",+ "tag_hex": "085544119aca0f7ca23a49e03e0ed56f",+ "ciphertext_hex": "69f189c19f923fbc74abaf18dd34226a241367f0e0a5fa3f4501c95fd0a7850b37b9",+ "envelope_hex": "42594f435f453245455f5631000102030405060708090a0b0c0d0e0f101112131415161718191a1b085544119aca0f7ca23a49e03e0ed56f69f189c19f923fbc74abaf18dd34226a241367f0e0a5fa3f4501c95fd0a7850b37b9"+ }+ ],+ "rejection_cases": [+ {+ "name": "iteration count above maximum",+ "mutate": {+ "offset": 12,+ "uint32_be": 2000000001+ },+ "expect_error": "BYOC_CORRUPTED_DATA",+ "$comment": "MUST be rejected before key derivation; a conforming impl returns in well under a second."+ },+ {+ "name": "iteration count below minimum",+ "mutate": {+ "offset": 12,+ "uint32_be": 1+ },+ "expect_error": "BYOC_CORRUPTED_DATA"+ },+ {+ "name": "unknown magic version",+ "mutate": {+ "offset": 0,+ "ascii": "BYOC_E2EE_V9"+ },+ "expect_error": "BYOC_CORRUPTED_DATA"+ },+ {+ "name": "in-range iteration tamper caught by AAD",+ "mutate": {+ "offset": 12,+ "uint32_be": 664000+ },+ "expect_error": "BYOC_AUTH_REQUIRED",+ "$comment": "Passes the range check, then fails the GCM tag: both layers must be present."+ },+ {+ "name": "wrong passphrase",+ "passphrase": "not-the-right-passphrase",+ "expect_error": "BYOC_AUTH_REQUIRED"+ },+ {+ "name": "truncated below header length",+ "truncate_to": 20,+ "expect_error": "BYOC_CORRUPTED_DATA"+ }+ ]+}diff --git a/spec/fixtures/path-encoding.json b/spec/fixtures/path-encoding.jsonnew file mode 100644index 0000000..7849660--- /dev/null+++ b/spec/fixtures/path-encoding.json@@ -0,0 +1,41 @@+{+ "$comment": "BYOC shared conformance vectors for RFC 3986 path encoding. This determines the actual S3 object key and WebDAV URL a file is stored under. Drift here means one SDK writes to a key another SDK cannot address. Unreserved characters (A-Za-z0-9 and - . _ ~) MUST pass through unencoded; everything else MUST be percent-encoded with uppercase hex.",+ "version": 1,+ "rfc3986_uri_encode": {+ "$comment": "rfc3986UriEncode(input, encode_slash) -> expected. Note that ! ' ( ) * are encoded even though encodeURIComponent in JavaScript leaves them alone; implementations must not rely on a language's built-in URL escaper without checking this set.",+ "cases": [+ { "input": "hello", "encode_slash": true, "expected": "hello" },+ { "input": "a b", "encode_slash": true, "expected": "a%20b" },+ { "input": "draft#2", "encode_slash": true, "expected": "draft%232" },+ { "input": "what?", "encode_slash": true, "expected": "what%3F" },+ { "input": "a&b", "encode_slash": true, "expected": "a%26b" },+ { "input": "c+d", "encode_slash": true, "expected": "c%2Bd" },+ { "input": "100%done", "encode_slash": true, "expected": "100%25done" },+ { "input": "Bob's", "encode_slash": true, "expected": "Bob%27s" },+ { "input": "bang!", "encode_slash": true, "expected": "bang%21" },+ { "input": "paren(1)", "encode_slash": true, "expected": "paren%281%29" },+ { "input": "star*", "encode_slash": true, "expected": "star%2A" },+ { "input": "tilde~x", "encode_slash": true, "expected": "tilde~x", "note": "tilde is unreserved in RFC 3986 and must NOT be encoded" },+ { "input": "dash-dot.under_score", "encode_slash": true, "expected": "dash-dot.under_score", "note": "all unreserved" },+ { "input": "café", "encode_slash": true, "expected": "caf%C3%A9", "note": "UTF-8 bytes, uppercase hex" },+ { "input": "日本語", "encode_slash": true, "expected": "%E6%97%A5%E6%9C%AC%E8%AA%9E" },+ { "input": "a/b", "encode_slash": true, "expected": "a%2Fb" },+ { "input": "a/b", "encode_slash": false, "expected": "a/b" },+ { "input": "x y/z#1", "encode_slash": false, "expected": "x%20y/z%231" }+ ]+ },+ "encode_path_segments": {+ "$comment": "encodePathSegments(input) -> expected. Splits on '/', encodes each segment with encode_slash=true, rejoins with '/'. Leading and trailing slashes are trimmed. It does NOT collapse duplicate interior slashes -- that is normalizeVirtualPath's job, and encoding is always applied to an already-normalized path.",+ "cases": [+ { "input": "notes/draft#2.pdf", "expected": "notes/draft%232.pdf", "note": "the '#' truncation bug this fixture exists to prevent" },+ { "input": "notes/what?.txt", "expected": "notes/what%3F.txt", "note": "the '?' truncation bug this fixture exists to prevent" },+ { "input": "Q3 report/a b.pdf", "expected": "Q3%20report/a%20b.pdf" },+ { "input": "docs/café/naïve.txt", "expected": "docs/caf%C3%A9/na%C3%AFve.txt" },+ { "input": "notes/Bob's Notes.pdf", "expected": "notes/Bob%27s%20Notes.pdf" },+ { "input": "/lead/trail/", "expected": "lead/trail" },+ { "input": "a//b", "expected": "a//b", "note": "interior duplicate slashes are preserved, not collapsed" },+ { "input": "", "expected": "" },+ { "input": "single.txt", "expected": "single.txt" }+ ]+ }+}diff --git a/spec/fixtures/path-normalization.json b/spec/fixtures/path-normalization.jsonnew file mode 100644index 0000000..5ff4685--- /dev/null+++ b/spec/fixtures/path-normalization.json@@ -0,0 +1,185 @@+{+ "$comment": "BYOC shared conformance vectors. Every SDK implementation MUST produce these exact results. Path normalization decides which folder bytes land in, so drift here means files written by one SDK are invisible to another. Do not edit expectations to match an implementation - fix the implementation.",+ "version": 1,+ "normalize": {+ "$comment": "normalizeVirtualPath(input) -> expected. A null input represents calling with no argument.",+ "cases": [+ {+ "name": "null input yields root",+ "input": null,+ "expected": ""+ },+ {+ "name": "empty string yields root",+ "input": "",+ "expected": ""+ },+ {+ "name": "whitespace-only yields root",+ "input": " ",+ "expected": ""+ },+ {+ "name": "bare filename is unchanged",+ "input": "avatar.jpg",+ "expected": "avatar.jpg"+ },+ {+ "name": "nested path is unchanged",+ "input": "users/123/avatar.jpg",+ "expected": "users/123/avatar.jpg"+ },+ {+ "name": "strips leading and trailing slashes",+ "input": "/users/123/avatar.jpg/",+ "expected": "users/123/avatar.jpg"+ },+ {+ "name": "trims surrounding whitespace",+ "input": " /documents/report.pdf ",+ "expected": "documents/report.pdf"+ },+ {+ "name": "collapses duplicate slashes",+ "input": "users///123////avatar.jpg",+ "expected": "users/123/avatar.jpg"+ },+ {+ "name": "collapses leading and trailing duplicate slashes",+ "input": "///a//b///c//",+ "expected": "a/b/c"+ },+ {+ "name": "converts Windows backslashes",+ "input": "users\\123\\avatar.jpg",+ "expected": "users/123/avatar.jpg"+ },+ {+ "name": "converts and trims backslashes",+ "input": "\\users\\123\\",+ "expected": "users/123"+ },+ {+ "name": "drops current-directory dot segments",+ "input": "./users/./123/avatar.jpg",+ "expected": "users/123/avatar.jpg"+ },+ {+ "name": "strips NUL bytes",+ "input": "a/bad\u0000name.txt",+ "expected": "a/badname.txt"+ },+ {+ "name": "strips newline and carriage return",+ "input": "documents/\nreport\r.pdf",+ "expected": "documents/report.pdf"+ },+ {+ "name": "strips BEL and unit-separator control chars",+ "input": "\u0007system/\u001fdata.bin",+ "expected": "system/data.bin"+ },+ {+ "name": "percent-encoded traversal is NOT decoded",+ "input": "a/..%2f../etc/passwd",+ "expected": "a/..%2f../etc/passwd"+ },+ {+ "name": "apostrophes are preserved verbatim",+ "input": "notes/Bob's Notes.pdf",+ "expected": "notes/Bob's Notes.pdf"+ },+ {+ "name": "unicode is preserved verbatim",+ "input": "docs/café/naïve.txt",+ "expected": "docs/café/naïve.txt"+ }+ ]+ },+ "normalize_errors": {+ "$comment": "These inputs MUST raise the BYOC error identified by code. TypeScript throws StorageError; Python raises the equivalent exception. The code string is the shared contract.",+ "cases": [+ {+ "name": "leading traversal",+ "input": "../secret.txt",+ "error_code": "BYOC_INVALID_INPUT"+ },+ {+ "name": "embedded traversal",+ "input": "users/../../etc/passwd",+ "error_code": "BYOC_INVALID_INPUT"+ },+ {+ "name": "bare double-dot segment",+ "input": "..",+ "error_code": "BYOC_INVALID_INPUT"+ },+ {+ "name": "backslash traversal",+ "input": "users\\..\\..\\etc",+ "error_code": "BYOC_INVALID_INPUT"+ }+ ]+ },+ "basename": {+ "$comment": "getBasename(input) -> expected",+ "cases": [+ {+ "input": "users/123/avatar.jpg",+ "expected": "avatar.jpg"+ },+ {+ "input": "/documents/reports/q3.pdf/",+ "expected": "q3.pdf"+ },+ {+ "input": "single_file.txt",+ "expected": "single_file.txt"+ },+ {+ "input": "",+ "expected": ""+ }+ ]+ },+ "dirname": {+ "$comment": "getDirname(input) -> expected",+ "cases": [+ {+ "input": "users/123/avatar.jpg",+ "expected": "users/123"+ },+ {+ "input": "avatar.jpg",+ "expected": ""+ },+ {+ "input": "/a/b/c/d.txt",+ "expected": "a/b/c"+ }+ ]+ },+ "split": {+ "$comment": "splitPath(input) -> expected",+ "cases": [+ {+ "input": "users/123/avatar.jpg",+ "expected": [+ "users",+ "123",+ "avatar.jpg"+ ]+ },+ {+ "input": "avatar.jpg",+ "expected": [+ "avatar.jpg"+ ]+ },+ {+ "input": "",+ "expected": []+ }+ ]+ }+}diff --git a/spec/fixtures/pkce.json b/spec/fixtures/pkce.jsonnew file mode 100644index 0000000..6e087f3--- /dev/null+++ b/spec/fixtures/pkce.json@@ -0,0 +1,34 @@+{+ "$comment": "PKCE (RFC 7636) conformance vectors. The S256 challenge must be the base64url-encoded SHA-256 of the ASCII verifier, with '+' -> '-', '/' -> '_', and '=' padding removed. A mismatch means one SDK's OAuth flow is rejected by Google while the other's succeeds.",+ "version": 1,+ "method": "S256",+ "rfc7636_appendix_b": {+ "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",+ "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",+ "note": "The verifier is the RFC 7636 Appendix B example."+ },+ "cases": [+ {+ "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",+ "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"+ },+ {+ "code_verifier": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",+ "code_challenge": "ZtNPunH49FD35FWYhT5Tv8I7vRKQJ8uxMaL0_9eHjNA"+ },+ {+ "code_verifier": "0123456789-._~abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",+ "code_challenge": "t2KVOUuyELfjjMQPpKmHeSqwrC_Mmzwb1J3882hbB4c"+ },+ {+ "code_verifier": "short-but-valid-verifier-with-43-characters",+ "code_challenge": "oKEcL_CDpJTLyaXJMJvjai6Y-DPZ8LjyScDahPfClxQ"+ }+ ],+ "verifier_rules": {+ "min_length": 43,+ "max_length": 128,+ "charset": "unreserved: A-Z a-z 0-9 - . _ ~",+ "$comment": "generateCodeVerifier must produce a value in this range using a cryptographically secure RNG."+ }+}diff --git a/spec/fixtures/provider-metadata.json b/spec/fixtures/provider-metadata.jsonnew file mode 100644index 0000000..2fb18b6--- /dev/null+++ b/spec/fixtures/provider-metadata.json@@ -0,0 +1,65 @@+{+ "$comment": "BYOC provider-side metadata contract. These key names are WIRE FORMAT, not API surface. They are written into the user's cloud account and read back by any SDK in any language. A Python implementation MUST write the literal camelCase key 'byocVirtualPath' even though snake_case would be idiomatic -- renaming it makes files written by one SDK invisible to another.",+ "version": 1,+ "reserved_key_prefix": {+ "value": "byoc",+ "$comment": "Keys beginning with 'byoc' are reserved for BYOC itself. User-supplied metadata keys MUST NOT collide with them; implementations should let BYOC's own keys win on conflict."+ },+ "keys": {+ "virtual_path": {+ "wire_name": "byocVirtualPath",+ "value": "the normalized virtual path, exactly as produced by normalizeVirtualPath",+ "required_for": ["google-drive"],+ "not_used_by": ["s3-compatible", "webdav"],+ "$comment": "Google Drive addresses files by opaque IDs, so the virtual path is not recoverable from the provider's own structure and must be stored alongside the file. S3 and WebDAV use the encoded path AS the object key, so the path is self-describing and no sidecar is written. Do not add it to those adapters -- it would change existing object metadata for no benefit."+ }+ },+ "provider_bindings": {+ "google-drive": {+ "mechanism": "files.appProperties",+ "key_transform": "none",+ "$comment": "appProperties is a flat string->string map, private to the OAuth client that wrote it. Keys are case-sensitive and stored verbatim.",+ "example": {+ "virtual_path_input": "users/123/Bob's Notes.pdf",+ "appProperties": { "byocVirtualPath": "users/123/Bob's Notes.pdf" }+ },+ "example_with_user_metadata": {+ "virtual_path_input": "reports/q3.pdf",+ "user_metadata": { "author": "Alice", "reviewStatus": "final" },+ "appProperties": {+ "byocVirtualPath": "reports/q3.pdf",+ "author": "Alice",+ "reviewStatus": "final"+ },+ "$comment": "User metadata is merged in alongside BYOC's own keys, preserving the caller's key casing."+ }+ },+ "s3-compatible": {+ "mechanism": "x-amz-meta-* request headers",+ "key_transform": "lowercase",+ "$comment": "Each user metadata key K is sent as the header 'x-amz-meta-' + lowercase(K). S3 lowercases metadata keys itself, so an implementation that preserves case will still read back lowercase and mismatch. No byocVirtualPath is written -- the object key is the path.",+ "example": {+ "virtual_path_input": "reports/q3.pdf",+ "user_metadata": { "Author": "Alice", "reviewStatus": "final" },+ "headers": {+ "x-amz-meta-author": "Alice",+ "x-amz-meta-reviewstatus": "final"+ }+ }+ },+ "webdav": {+ "mechanism": "none",+ "$comment": "This adapter does not persist BYOC metadata. The encoded path is the resource URL, so the virtual path is self-describing."+ }+ },+ "round_trip_cases": {+ "$comment": "For the cross-SDK interop suite: SDK A uploads with these inputs, SDK B reads the file back and MUST recover the same virtual path and metadata.",+ "cases": [+ { "path": "users/123/avatar.jpg", "metadata": {} },+ { "path": "notes/Bob's Notes.pdf", "metadata": {}, "note": "apostrophe must survive the Drive query escape round-trip" },+ { "path": "notes/draft#2.pdf", "metadata": {}, "note": "hash must survive S3 key encoding" },+ { "path": "docs/café/naïve.txt", "metadata": {}, "note": "unicode round-trip" },+ { "path": "reports/q3.pdf", "metadata": { "author": "Alice" } }+ ]+ }+}diff --git a/spec/fixtures/sigv4.json b/spec/fixtures/sigv4.jsonnew file mode 100644index 0000000..efb3aa5--- /dev/null+++ b/spec/fixtures/sigv4.json@@ -0,0 +1,82 @@+{+ "$comment": "AWS Signature Version 4 conformance vectors for BYOC's S3-compatible adapter. The first vector's signature was independently verified against a clean-room implementation written directly from the AWS specification, so it is an external check rather than a self-generated snapshot. Every SDK must reproduce these byte-for-byte or it cannot talk to S3/R2/MinIO.",+ "version": 1,+ "credentials": {+ "access_key_id": "AKIDEXAMPLE",+ "secret_access_key": "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY",+ "region": "us-east-1",+ "service": "s3"+ },+ "datetime_iso": "2013-05-24T00:00:00.000Z",+ "amz_date": "20130524T000000Z",+ "date_stamp": "20130524",+ "empty_body_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",+ "rules": {+ "body_hash": "sha256 of the request body; for an empty body use the sha256 of the empty string (NOT 'UNSIGNED-PAYLOAD'). Presigned URLs are the exception and use UNSIGNED-PAYLOAD.",+ "header_normalization": "lowercase the key, strip surrounding whitespace from the value, collapse internal whitespace runs to a single space, then sort by key",+ "canonical_query": "RFC 3986 encode key and value (slashes encoded), sort by encoded key then encoded value, join with &"+ },+ "canonical_query": [+ {+ "url": "https://b.example.com/?prefix=my%20folder&list-type=2&delimiter=%2F",+ "expected": "delimiter=%2F&list-type=2&prefix=my%20folder"+ },+ {+ "url": "https://b.example.com/?b=2&a=1&c=3",+ "expected": "a=1&b=2&c=3"+ },+ {+ "url": "https://b.example.com/?key=a+b",+ "expected": "key=a%20b",+ "note": "'+' in a query value decodes to a space and must re-encode as %20, never '+'"+ }+ ],+ "vectors": [+ {+ "name": "GET with x-amz-storage-class, empty body",+ "method": "GET",+ "url": "https://example.amazonaws.com/test.txt",+ "headers": {+ "x-amz-storage-class": "REDUCED_REDUNDANCY"+ },+ "body": null,+ "signed_headers": "host;x-amz-content-sha256;x-amz-date;x-amz-storage-class",+ "signature": "c29c0c4b3f775eacb23837eb912405953619018f2417926a9ed48e32352e0e3b",+ "authorization": "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-storage-class, Signature=c29c0c4b3f775eacb23837eb912405953619018f2417926a9ed48e32352e0e3b",+ "note": "independently verified against a clean-room SigV4 implementation"+ },+ {+ "name": "PUT with mixed-case Content-Type and an encoded key",+ "method": "PUT",+ "url": "https://examplebucket.s3.amazonaws.com/notes/draft%232.pdf",+ "headers": {+ "Content-Type": "text/plain"+ },+ "body": "hello world",+ "signed_headers": "content-type;host;x-amz-content-sha256;x-amz-date",+ "signature": "ec2d72d10e743af6aeb4e5ca9dec070f563c2d00c2c353fab2f9fb4928f3f1ec",+ "authorization": "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date, Signature=ec2d72d10e743af6aeb4e5ca9dec070f563c2d00c2c353fab2f9fb4928f3f1ec",+ "note": "header casing must not change the signature"+ },+ {+ "name": "GET ListObjectsV2 with multiple query params",+ "method": "GET",+ "url": "https://examplebucket.s3.amazonaws.com/?list-type=2&prefix=my%20folder&delimiter=%2F",+ "headers": {},+ "body": null,+ "signed_headers": "host;x-amz-content-sha256;x-amz-date",+ "signature": "3bacd7298f702f149270540d6ecb61d69a92a7528df267c565ef91dad4e23100",+ "authorization": "AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20130524/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=3bacd7298f702f149270540d6ecb61d69a92a7528df267c565ef91dad4e23100"+ }+ ],+ "presigned": [+ {+ "name": "presigned GET, 3600s",+ "method": "GET",+ "url": "https://examplebucket.s3.amazonaws.com/notes/draft%232.pdf",+ "expires_in_seconds": 3600,+ "expected_url": "https://examplebucket.s3.amazonaws.com/notes/draft%232.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=cc2cca2204792848aefc4669b4f6d2bbcae83aaa4bb4d1aa2ddcfbba5428ccd1",+ "note": "presigned URLs sign with UNSIGNED-PAYLOAD and host-only signed headers"+ }+ ]+}diff --git a/tsconfig.base.json b/tsconfig.base.jsonnew file mode 100644index 0000000..25da7c7--- /dev/null+++ b/tsconfig.base.json@@ -0,0 +1,28 @@+{+ "compilerOptions": {+ "target": "ES2022",+ "module": "NodeNext",+ "moduleResolution": "NodeNext",+ "lib": ["ES2022", "DOM"],+ "declaration": true,+ "declarationMap": true,+ "sourceMap": true,+ "composite": true,+ "strict": true,+ "noImplicitAny": true,+ "strictNullChecks": true,+ "strictFunctionTypes": true,+ "strictBindCallApply": true,+ "strictPropertyInitialization": true,+ "noImplicitThis": true,+ "alwaysStrict": true,+ "noUnusedLocals": true,+ "noUnusedParameters": true,+ "noImplicitReturns": true,+ "noFallthroughCasesInSwitch": true,+ "noUncheckedIndexedAccess": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "forceConsistentCasingInFileNames": true+ }+}diff --git a/vitest.config.ts b/vitest.config.tsnew file mode 100644index 0000000..33944fa--- /dev/null+++ b/vitest.config.ts@@ -0,0 +1,13 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ globals: true,+ environment: "node",+ include: ["packages/**/tests/**/*.test.ts"],+ coverage: {+ provider: "v8",+ reporter: ["text", "json", "html"]+ }+ }+});