diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f08d440 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,66 @@ +# .github/dependabot.yml +# +# Version updates for the Bun workspace. +# +# Preconditions this repository meets. Dependabot's `bun` ecosystem went GA on +# 2025-02-13 -- https://github.blog/changelog/2025-02-13-dependabot-version-updates-now-support-the-bun-package-manager-ga/ +# -- and needs Bun >= 1.1.39 and the text-based `bun.lock`, not the legacy +# binary `bun.lockb`. `.bun-version` pins 1.3.14 and `bun.lock` is JSON +# (`"lockfileVersion": 1` on its second line). +# +# One hard limit and one caution, stated here rather than diagnosed later from +# a confusing PR: +# +# * HARD: `bun` covers VERSION updates only. Dependabot issues no SECURITY +# updates for this ecosystem, so an advisory against a dependency will not +# arrive as a PR. `bun run audit` (`bun audit --audit-level=high --prod`) +# is a CI step and stays the thing that catches those. +# * CAUTION: treat lockfile updates under a workspace layout as unproven. +# dependabot/dependabot-core#14223 is open (2026-02-19), titled "Dependabot +# does not fix bun.lock in environment which using npm workspace", and the +# symptom matches this repository's shape -- `workspaces.packages: +# ["packages/*"]` in the root package.json, eleven packages. It is NOT a +# confirmed defect of the configuration below: the reporter's linked config +# declares `package-ecosystem: "npm"` with `enable-beta-ecosystems: true`, +# not `bun`, so the published repro does not exercise this file. (#11602, +# closed, is the older single-package report.) If it does bite, it shows up +# as a no-op PR, or as a manifest bump with a stale lockfile -- the second +# kind fails CI at `bun install --frozen-lockfile`, the first step of the +# run, and that failure is the tooling, not the bump. Re-run `bun install` +# locally and commit `bun.lock` onto the PR branch. +# +# This file is inert until it reaches the repository's DEFAULT branch -- +# Dependabot reads its configuration only from there, and the default is `main` +# while the MVP work integrates on `mvp` (see CONTRIBUTING.md, "Branching"). +# To activate it before that merge, cherry-pick it onto `main` AND add +# `target-branch: 'mvp'` to the entry below, so the PRs land where the work is. +# Drop that line again once `mvp` has merged. +# +# No `github-actions` ecosystem block: deliberately out of scope for the ticket +# that added this file. The three actions in use -- actions/checkout@v4, +# oven-sh/setup-bun@v2, actions/setup-node@v4 -- are pinned by major tag. +version: 2 + +updates: + - package-ecosystem: 'bun' + directory: '/' + schedule: + interval: 'weekly' + day: 'monday' + # 5 is Dependabot's own default, written out so it reads as a decision + # rather than an omission. Deliberately not RAISED: every PR here runs the + # full 20-step CI, including a double clean build for the reproducibility + # gate, and the caution above means some fraction of them may be no-ops. + open-pull-requests-limit: 5 + commit-message: + prefix: 'chore' + include: 'scope' + groups: + # One PR for the routine drift. A major bump is excluded, so it arrives on + # its own branch and the breaking change gets reviewed alone. + minor-and-patch: + patterns: + - '*' + update-types: + - 'minor' + - 'patch' diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..594b673 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,40 @@ +# Code of Conduct + +## Our pledge + +We as members, contributors, and maintainers pledge to make participation in +the dexpace Node.js SDK 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, +religion, or sexual identity and orientation. + +## Our standards + +Examples of behavior 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 +- Focusing on what is best for the community + +Examples of unacceptable behavior: + +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the maintainers at +[oaljarrah@dexpace.org](mailto:oaljarrah@dexpace.org). 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. + +## Attribution + +This Code of Conduct is adapted from the +[Contributor Covenant](https://www.contributor-covenant.org), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..565f107 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing + +Thanks for your interest in the Dexpace Node.js SDK. External pull requests +are welcome — this page covers everything you need to get a change merged. + +## Setup + +The repository is a [Bun](https://bun.sh)-managed workspace of eleven +packages, nine of them published. One install provisions everything along +with the dev toolchain. The Bun version is pinned in `.bun-version`, which +CI resolves — use it: + +```bash +git clone https://github.com/dexpace/nodejs-sdk.git +cd nodejs-sdk +bun install --frozen-lockfile +``` + +## Quality gates + +Every pull request must pass the same 20 steps CI runs, across two jobs and +on both Node 20.3 and current LTS. One command runs all of them locally, in +CI's own order: + +```bash +node .claude/skills/ci-preflight/run-ci.mjs --clean +``` + +Run it before opening a PR; `--clean` starts it from the tree CI checks out +rather than a warm one. A consumer-facing change also needs a changeset — +`bun run changeset`, not `bunx changeset`, because the wrapper renames the +generated file — and a change to a package's exports needs its API report +regenerated with `api:local` in that package and committed. + +## Conventions + +The full convention set lives in [`CLAUDE.md`](CLAUDE.md). The essentials: + +- **Branch off `mvp`, not `main`.** `mvp` is the integration branch and + merges into `main` when the MVP is complete; GitHub still offers `main` + as the base, so change it. +- **`bun run build` before `bun run test`.** Every package reaches + `@dexpace/core` through `packages/core/dist/`; without a build the tests + cannot resolve it, and against a stale one they pass over yesterday's core. +- **`bun run test` is the only invocation that reaches both test trees** + (`bun test ./packages ./tests`) — a bare `bun test` silently runs + `packages/` alone. `bun run test:node` is the separate Node-runtime suite. +- **ESM-only, NodeNext**: relative imports carry `.js` even in `.ts` source, + type-only imports need `import type`, and `erasableSyntaxOnly` rules out + enums and namespaces. +- **No new runtime dependencies.** Every published package ships a + hard-committed empty `dependencies`; new third-party needs belong behind + the `Transport` or `Serde` seams, or in a new adapter package (SEAM-1, + gate-enforced). +- **MIT licence header** (`// SPDX-License-Identifier: MIT`) on line 1 of + every source file, src and tests alike; functions capped at 70 lines. + +## Commit messages + +Use the prefixes the history already follows: + +| Prefix | Use for | +|----------|----------------------------------| +| `feat:` | new features | +| `fix:` | bug fixes | +| `chore:` | refactors and cleanup | +| `docs:` | documentation-only changes | +| `test:` | tests only | +| `ci:` | CI configuration | + +## Reporting issues + +Open one at [github.com/dexpace/nodejs-sdk/issues](https://github.com/dexpace/nodejs-sdk/issues). +For security vulnerabilities, follow [`SECURITY.md`](SECURITY.md) instead of +opening a public issue. diff --git a/LICENSE b/LICENSE.md similarity index 86% rename from LICENSE rename to LICENSE.md index d75d8bf..1724c32 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,6 +1,6 @@ -MIT License +# MIT License -Copyright (c) 2026 dexpace +Copyright (c) 2026 dexpace and Omar Aljarrah Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4759430 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ +# Security Policy + +## Supported versions + +Nothing has shipped yet: every package in the workspace is at `0.0.0` and +none has been published to npm, so there is no released version to support +and no patched release to point at. Until the first release, the supported +revision is the tip of `mvp` — report against a commit SHA. + +## Reporting a vulnerability + +Please **do not** open a public issue for security vulnerabilities. + +Instead, report privately by email to +[oaljarrah@dexpace.org](mailto:oaljarrah@dexpace.org) with `[SECURITY]` in +the subject line. + +Include what you can of the following: + +- The affected package(s), and the commit SHA and Bun/Node.js versions you + reproduced against +- A description of the vulnerability and its impact +- Steps or a proof of concept to reproduce it + +You can expect an acknowledgement within a few days. Please allow time for +a fix to land and be released before disclosing publicly. + +## Scope notes + +- The SDK is a **toolkit**, not a service: `@dexpace/core` executes no + network I/O of its own, and reaches into `node:` exactly once, for + `AsyncLocalStorage`. Transport-level vulnerabilities (TLS, connection + handling, message parsing) belong to whatever sits behind the `Transport` + seam — the runtime's global `fetch`, or `undici` for + `@dexpace/transport-undici` — report those upstream. +- In scope here: credential handling and challenge parsing + (`packages/core/src/auth/`), header/URL redaction in logging + (`packages/core/src/observability/redaction.ts`), redirect safety + (`Authorization` stripped on every re-issue, `Cookie` and + `Proxy-Authorization` cross-origin — `packages/core/src/redirect/decide.ts`), + and body capture (`packages/core/src/body/`, `@dexpace/body-file`). diff --git a/package.json b/package.json index acc6fc1..df86a9d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "name": "nodejs-sdk", "private": true, + "license": "MIT", "type": "module", "workspaces": { "packages": [