Skip to content

Commit 658b808

Browse files
niejingchuanniejingchuan
committed
feat: add BailingHub n8n community node
0 parents  commit 658b808

26 files changed

Lines changed: 9576 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
concurrency:
10+
group: ci-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
verify:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: '22'
21+
cache: npm
22+
- run: npm ci
23+
- run: npm run verify
24+
- run: npm pack --dry-run

‎.github/workflows/publish.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Publish
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*.*.*'
7+
8+
jobs:
9+
publish:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: read
13+
id-token: write
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version: '22'
19+
registry-url: 'https://registry.npmjs.org'
20+
cache: npm
21+
- name: Use an npm version with trusted publishing support
22+
run: npm install --global npm@latest
23+
- run: npm ci
24+
- run: node scripts/check-release-tag.mjs
25+
env:
26+
GITHUB_REF_NAME: ${{ github.ref_name }}
27+
- run: npm run verify
28+
- name: Publish with npm provenance
29+
run: |
30+
[ -n "$NPM_TOKEN" ] && npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
31+
npm publish --access public --provenance
32+
env:
33+
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dist
2+
node_modules
3+
.n8n
4+
*.tgz
5+
.DS_Store

‎.prettierrc.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
module.exports = {
2+
semi: true,
3+
trailingComma: 'all',
4+
bracketSpacing: true,
5+
useTabs: true,
6+
tabWidth: 2,
7+
arrowParens: 'always',
8+
singleQuote: true,
9+
quoteProps: 'as-needed',
10+
endOfLine: 'lf',
11+
printWidth: 100,
12+
};

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Changelog
2+
3+
## 0.1.0 - Unreleased
4+
5+
- Add BailingHub credentials with HTTPS-by-default validation.
6+
- Add Submit Governed Job, Get Job, and bounded Wait for Job operations.
7+
- Filter public workflow output and map upstream failures to bounded messages.
8+
- Restrict the dedicated credential to the BailingHub node and exclude the generic Custom
9+
API Call surface.
10+
- Add CI, npm provenance publishing, tests, privacy, security, and project-boundary docs.

‎CONTRIBUTING.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Contributing
2+
3+
Issues and pull requests are welcome.
4+
5+
Before submitting a change:
6+
7+
```bash
8+
npm install
9+
npm run verify
10+
npm pack --dry-run
11+
```
12+
13+
Keep protocol changes in the project that owns them:
14+
15+
- n8n UX, packaging, and adapter behavior belong here;
16+
- BailingHub Client API behavior belongs in BailingHub;
17+
- portable governance semantics belong in ACC.
18+
19+
Do not commit credentials, private workflow exports, deployment URLs, or production evidence.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 BailingHub Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎PRIVACY.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Privacy
2+
3+
`n8n-nodes-bailinghub` does not collect telemetry and does not send data to the project
4+
maintainers.
5+
6+
For **Submit Governed Job**, the node sends these fields to the BailingHub deployment chosen
7+
by the n8n operator:
8+
9+
- `request_id`;
10+
- `route`;
11+
- `input`.
12+
13+
For **Get Job** and **Wait for Job**, it sends the job ID in the request path. The Client Token
14+
is stored by n8n's credential system and added to the fixed BailingHub requests as an
15+
Authorization header. It is not made available to n8n's generic Custom API Call surface.
16+
17+
The adapter filters BailingHub job responses before returning them to the workflow. Internal
18+
metadata and dispatch configuration are not included. The deploying organization remains
19+
responsible for its n8n retention settings, BailingHub retention settings, business payloads,
20+
and applicable privacy obligations.

‎README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# n8n-nodes-bailinghub
2+
3+
`n8n-nodes-bailinghub` lets n8n workflows submit and monitor governed AI jobs through
4+
[BailingHub](https://github.com/bailinghub/bailinghub).
5+
6+
BailingHub sits between agents or automation workflows and existing business systems. It
7+
provides a control plane for route allowlists, risk-aware tool governance, human approval
8+
intents, execution records, and auditability. This node is an independent adapter to its
9+
public Client API; it does not embed BailingHub or redefine ACC.
10+
11+
## Installation
12+
13+
Install the community package named `n8n-nodes-bailinghub` from n8n's community node UI,
14+
or install it in a self-hosted n8n deployment according to the
15+
[n8n community node guide](https://docs.n8n.io/integrations/community-nodes/installation/).
16+
17+
The package's verified-node status is tracked through its GitHub releases. The repository
18+
does not claim n8n verification until n8n has completed that review.
19+
20+
## Operations
21+
22+
| Operation | Purpose |
23+
| --- | --- |
24+
| Submit Governed Job | Calls `POST /run` with a request ID, allowed route, and task input. |
25+
| Get Job | Calls `GET /jobs/{job_id}` and returns a deliberately reduced public result. |
26+
| Wait for Job | Polls the same job for at most 60 seconds, then returns the terminal or latest state. |
27+
28+
The node never resubmits a task while waiting. If a wait times out, branch on
29+
`wait_timed_out: true` and continue polling later with the same job ID.
30+
31+
## Credentials
32+
33+
Create a dedicated BailingHub client in the BailingHub console and configure:
34+
35+
- **Base URL**: the deployment root, such as `https://hub.example.com`;
36+
- **Client Token**: the per-client token issued by BailingHub;
37+
- **Allow Insecure HTTP**: keep disabled unless a self-hosted n8n instance reaches
38+
BailingHub over a trusted private network without TLS.
39+
40+
Do not use the BailingHub administrator token. Route access and rate limits should be
41+
configured on the dedicated client. n8n's credential test verifies that the configured
42+
BailingHub deployment is reachable through its public health endpoint. The Client Token is
43+
validated by BailingHub on the first protected job request; a health check is not presented
44+
as proof that a token is valid.
45+
46+
## Security Boundary
47+
48+
This adapter intentionally exposes only BailingHub's public client surface:
49+
50+
- it does not call administrator trace or approval endpoints;
51+
- it does not expose approve or reject actions;
52+
- it does not accept acting-subject metadata in v1;
53+
- its dedicated credential is restricted to this node and is not exposed through n8n's
54+
generic Custom API Call surface;
55+
- it filters job responses so internal dispatch configuration, credentials, metadata, and
56+
administrator-only evidence do not enter n8n workflow output;
57+
- it maps upstream errors to bounded public messages rather than returning arbitrary bodies.
58+
59+
Trusted acting subjects must be established from an authenticated business-system boundary.
60+
They must not be copied from model output. Final business authorization remains in the
61+
business system.
62+
63+
## Typical Workflow
64+
65+
1. A trusted n8n trigger receives a business event.
66+
2. **Submit Governed Job** sends the task to a BailingHub route with a stable request ID.
67+
3. Store the returned `job_id`.
68+
4. Use **Wait for Job** for a short bounded wait, or schedule **Get Job** later.
69+
5. Branch on `status`, `terminal`, and `wait_timed_out`.
70+
6. Consume `result`, `report`, or `raw_result` only after checking the terminal status.
71+
72+
Approval workflow ownership remains outside this node. BailingHub can pause governed tool
73+
execution and emit approval intents through the deployment's configured approval channel.
74+
75+
An importable example is available at
76+
[`examples/submit-and-wait.workflow.json`](examples/submit-and-wait.workflow.json). Replace
77+
the route placeholder with a route allowed for the dedicated BailingHub client, then assign
78+
the same BailingHub credential to both BailingHub nodes.
79+
80+
## Compatibility
81+
82+
The adapter targets BailingHub's public `POST /run` and `GET /jobs/{job_id}` Client API and
83+
the `bailing.contract.v2.13` compatible contract family. See
84+
[docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for the tested matrix.
85+
86+
## Project Boundaries
87+
88+
See [docs/PROJECT_BOUNDARIES.md](docs/PROJECT_BOUNDARIES.md). The dependency direction is
89+
strictly one-way:
90+
91+
```text
92+
n8n-nodes-bailinghub -> BailingHub public Client API
93+
BailingHub may consume ACC declarations
94+
ACC has no dependency on either implementation
95+
```
96+
97+
## Privacy
98+
99+
The node has no telemetry. It sends the configured request ID, route, and task input only to
100+
the BailingHub URL chosen by the n8n operator. See [PRIVACY.md](PRIVACY.md).
101+
102+
## Resources
103+
104+
- [BailingHub](https://github.com/bailinghub/bailinghub)
105+
- [BailingHub integration guide](https://github.com/bailinghub/bailinghub/blob/main/docs/INTEGRATION.en.md)
106+
- [n8n community node documentation](https://docs.n8n.io/integrations/creating-nodes/)
107+
- [Agent Capability Contract](https://agentcapability.org/)
108+
109+
## Development
110+
111+
```bash
112+
npm install
113+
npm run verify
114+
npm run dev
115+
```
116+
117+
`npm run verify` runs the n8n linter, builds the package, and executes the contract-focused
118+
tests. Releases are published from GitHub Actions with npm provenance.
119+
120+
## License
121+
122+
MIT

‎SECURITY.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Security Policy
2+
3+
Please report vulnerabilities through a private GitHub Security Advisory in this repository.
4+
Do not include production tokens, private deployment URLs, personal data, or raw business
5+
payloads in a public issue.
6+
7+
## Supported Versions
8+
9+
Security fixes are provided for the latest published minor version.
10+
11+
## Adapter Boundary
12+
13+
This package stores credentials through n8n's credential system and sends requests only to
14+
the operator-configured BailingHub URL. It does not make administrator API calls, resolve
15+
business authorization, or independently approve tools. The BailingHub credential is
16+
restricted to this node and deliberately does not enable n8n's generic Custom API Call
17+
surface.

0 commit comments

Comments
 (0)