Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -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'
40 changes: 40 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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.
75 changes: 75 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
12 changes: 6 additions & 6 deletions LICENSE → LICENSE.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
41 changes: 41 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -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`).
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"name": "nodejs-sdk",
"private": true,
"license": "MIT",
"type": "module",
"workspaces": {
"packages": [
Expand Down
Loading