From 5d3cffdc4af98b74b1f2f1e99c9ac822e3afc36a Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Wed, 29 Jul 2026 10:39:38 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=92=20Harden=20supply=20chain=20and=20?= =?UTF-8?q?expand=20the=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Security: - Add SECURITY.md with a private disclosure path and token-handling scope - Pin every GitHub Action to a full commit SHA (with a version comment) Docs/marketing: - Add an overview table with npm version badges for all 10 packages - Document richtext, mcp-server, cli and mgmt-client, which were missing - Fix the website link (pointed at a stale Discord invite) and unify the Discord invite - Link Discussions and SECURITY.md from Support Also adds issue forms for bug reports and feature requests. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NpVQZRfDzRMxL9NUf7Q5qf --- .github/ISSUE_TEMPLATE/bug_report.yml | 80 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 14 ++++ .github/ISSUE_TEMPLATE/feature_request.yml | 52 ++++++++++++ .github/actions/setup/action.yml | 4 +- .github/workflows/ci.yml | 6 +- .github/workflows/release.yml | 4 +- CONTRIBUTING.md | 2 +- README.md | 97 +++++++++++++++++++--- SECURITY.md | 58 +++++++++++++ 9 files changed, 299 insertions(+), 18 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b2737e6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,80 @@ +name: ๐Ÿ› Bug report +description: Something in one of the b10cks SDK packages does not work as documented. +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a report. + + **Do not report security vulnerabilities here** โ€“ use + [private reporting](https://github.com/b10cks/sdk/security/advisories/new) instead. + + - type: dropdown + id: package + attributes: + label: Package + description: Which package is affected? + multiple: true + options: + - '@b10cks/client' + - '@b10cks/richtext' + - '@b10cks/vue' + - '@b10cks/nuxt' + - '@b10cks/react' + - '@b10cks/next' + - '@b10cks/svelte' + - '@b10cks/mcp-server' + - '@b10cks/cli' + - '@b10cks/mgmt-client' + - Not sure + validations: + required: true + + - type: input + id: version + attributes: + label: Package version + placeholder: e.g. 2.3.1 + validations: + required: true + + - type: textarea + id: what-happened + attributes: + label: What happened? + description: What did you expect to happen, and what happened instead? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: A minimal reproduction (repo, StackBlitz or code snippet) gets this fixed much faster. + value: | + 1. + 2. + 3. + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Node version, package manager, framework version, browser/runtime. + render: text + placeholder: | + Node: 24.7.0 + Package manager: pnpm 11.17.0 + Framework: Nuxt 4.x + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant logs or errors + description: Paste any error output. **Redact access tokens before posting.** + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..90adbf2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: false +contact_links: + - name: ๐Ÿ’ฌ Question or idea + url: https://github.com/b10cks/sdk/discussions + about: Ask usage questions, propose ideas or share what you built. + - name: ๐Ÿ” Report a security vulnerability + url: https://github.com/b10cks/sdk/security/advisories/new + about: Please report vulnerabilities privately โ€“ never as a public issue. + - name: ๐Ÿ“– Documentation + url: https://www.b10cks.com/docs + about: Guides and API reference for b10cks. + - name: ๐Ÿ—จ๏ธ Discord + url: https://discord.gg/mdcDktFFcp + about: Chat with the community. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..1c5d258 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,52 @@ +name: โœจ Feature request +description: Suggest a new capability for one of the b10cks SDK packages. +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Open-ended ideas are often a better fit for + [Discussions](https://github.com/b10cks/sdk/discussions). Use this form when you have a + concrete change in mind. + + - type: dropdown + id: package + attributes: + label: Package + multiple: true + options: + - '@b10cks/client' + - '@b10cks/richtext' + - '@b10cks/vue' + - '@b10cks/nuxt' + - '@b10cks/react' + - '@b10cks/next' + - '@b10cks/svelte' + - '@b10cks/mcp-server' + - '@b10cks/cli' + - '@b10cks/mgmt-client' + - New package + validations: + required: true + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the use case you are stuck on, not just the solution you have in mind. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed API or behaviour + description: Sketch the API you would like. Code samples welcome. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered + description: Workarounds you tried, and why they fall short. diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml index 7115fd3..d64cfbb 100644 --- a/.github/actions/setup/action.yml +++ b/.github/actions/setup/action.yml @@ -11,9 +11,9 @@ runs: using: composite steps: # Version comes from the `packageManager` field in package.json. - - uses: pnpm/action-setup@v6 + - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6 - - uses: actions/setup-node@v7 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7 with: node-version: ${{ inputs.node-version }} cache: pnpm diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4aaa308..e4bea81 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,7 @@ jobs: name: Lint & format runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - uses: ./.github/actions/setup - name: Lint @@ -35,7 +35,7 @@ jobs: matrix: node: ['24', '26'] steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - uses: ./.github/actions/setup with: node-version: ${{ matrix.node }} @@ -55,7 +55,7 @@ jobs: runs-on: ubuntu-latest if: github.event_name == 'pull_request' && github.head_ref != 'changeset-release/main' && !contains(github.event.pull_request.labels.*.name, 'skip-changeset') steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: fetch-depth: 0 - uses: ./.github/actions/setup diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7abc43e..c251cb4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -22,7 +22,7 @@ jobs: env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 with: fetch-depth: 0 @@ -38,7 +38,7 @@ jobs: - name: Create version PR or publish id: changesets - uses: changesets/action@v1.9.0 + uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1.9.0 with: version: pnpm run changeset:version publish: pnpm run release diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 509e810..505588c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,6 @@ from a developer machine. If you have any questions or need support, feel free to reach out to the maintainers. We are here to help! -1. You can check the [b10cks documentation](https://docs.b10cks.com/). +1. You can check the [b10cks documentation](https://www.b10cks.com/docs). 2. Open an issue in this repository if you encounter any problems or have questions about the SDKs. 3. Join our [Discord community](https://discord.gg/coders_cantina) for community support. diff --git a/README.md b/README.md index e1daca4..aef25c8 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,30 @@ [![CI](https://github.com/b10cks/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/b10cks/sdk/actions/workflows/ci.yml) [![Release](https://github.com/b10cks/sdk/actions/workflows/release.yml/badge.svg)](https://github.com/b10cks/sdk/actions/workflows/release.yml) +[![npm](https://img.shields.io/npm/v/@b10cks/client?label=%40b10cks%2Fclient)](https://www.npmjs.com/package/@b10cks/client) +[![License](https://img.shields.io/npm/l/@b10cks/client)](./LICENSE) -Official JavaScript/TypeScript SDKs for [b10cks](https://b10cks.com) โ€“ a modern headless CMS and content management platform. +Official JavaScript/TypeScript SDKs for [b10cks](https://www.b10cks.com) โ€“ a modern headless CMS and content management platform. -This monorepo contains multiple packages that enable seamless integration of b10cks into your web applications. +Fully typed, framework-agnostic at the core, with first-party integrations for Vue, Nuxt, React, +Next.js and Svelte โ€“ plus a CLI and an [MCP server](./packages/mcp-server) that let you (and your AI +coding agent) drive the b10cks Management API directly. ## ๐Ÿ“ฆ Packages +| Package | Version | What it does | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | +| [`@b10cks/client`](./packages/client) | [![npm](https://img.shields.io/npm/v/@b10cks/client)](https://www.npmjs.com/package/@b10cks/client) | Framework-agnostic Data API client | +| [`@b10cks/richtext`](./packages/richtext) | [![npm](https://img.shields.io/npm/v/@b10cks/richtext)](https://www.npmjs.com/package/@b10cks/richtext) | Rich text โ†’ HTML renderer | +| [`@b10cks/vue`](./packages/vue) | [![npm](https://img.shields.io/npm/v/@b10cks/vue)](https://www.npmjs.com/package/@b10cks/vue) | Vue 3 plugin, composables and live-edit directives | +| [`@b10cks/nuxt`](./packages/nuxt) | [![npm](https://img.shields.io/npm/v/@b10cks/nuxt)](https://www.npmjs.com/package/@b10cks/nuxt) | Nuxt 4 module | +| [`@b10cks/react`](./packages/react) | [![npm](https://img.shields.io/npm/v/@b10cks/react)](https://www.npmjs.com/package/@b10cks/react) | React provider and hooks | +| [`@b10cks/next`](./packages/next) | [![npm](https://img.shields.io/npm/v/@b10cks/next)](https://www.npmjs.com/package/@b10cks/next) | Next.js integration layer | +| [`@b10cks/svelte`](./packages/svelte) | [![npm](https://img.shields.io/npm/v/@b10cks/svelte)](https://www.npmjs.com/package/@b10cks/svelte) | Svelte context, stores and actions | +| [`@b10cks/mcp-server`](./packages/mcp-server) | [![npm](https://img.shields.io/npm/v/@b10cks/mcp-server)](https://www.npmjs.com/package/@b10cks/mcp-server) | MCP server for the Management API | +| [`@b10cks/cli`](./packages/cli) | [![npm](https://img.shields.io/npm/v/@b10cks/cli)](https://www.npmjs.com/package/@b10cks/cli) | Scaffolding, schema sync and type generation | +| [`@b10cks/mgmt-client`](./packages/mgmt-client) | [![npm](https://img.shields.io/npm/v/@b10cks/mgmt-client)](https://www.npmjs.com/package/@b10cks/mgmt-client) | Typed Management API client | + ### [@b10cks/client](./packages/client) Framework-agnostic core for the [b10cks](https://www.b10cks.com) Data API. @@ -86,6 +103,57 @@ Next.js integration layer for [b10cks](https://www.b10cks.com) on top of the Rea npm install @b10cks/next @b10cks/react @b10cks/client ``` +### [@b10cks/richtext](./packages/richtext) + +Framework-agnostic rich text rendering for the [b10cks](https://www.b10cks.com) rich text field. + +- Renders the editor document tree to HTML +- Escapes text and attributes, sanitizes `href`/`src` URL schemes +- Pluggable resolvers for internal links and custom nodes +- No framework or DOM dependency + +```bash +npm install @b10cks/richtext +``` + +### [@b10cks/mcp-server](./packages/mcp-server) + +Model Context Protocol server that exposes the [b10cks](https://www.b10cks.com) Management API to AI +coding agents such as Claude Code, Cursor and Claude Desktop. + +- Block definitions, content, redirects, data sources, releases and automations as MCP tools +- Lets an agent read and evolve your content model without hand-written glue +- Built on `@b10cks/mgmt-client` + +```bash +npx @b10cks/mcp-server +``` + +### [@b10cks/cli](./packages/cli) + +Command line interface for the [b10cks](https://www.b10cks.com) Management API. + +- Project scaffolding and framework wiring (`init`, `kickstart`) +- Schema `pull` / `diff` / `push` with a lockfile +- TypeScript type generation from your block schema +- Credentials stored in `~/.netrc` with `0600` permissions + +```bash +npm install -D @b10cks/cli +``` + +### [@b10cks/mgmt-client](./packages/mgmt-client) + +Typed client for the [b10cks](https://www.b10cks.com) Management API. + +- Full CRUD across spaces, blocks, content, assets and more +- Shared foundation for `@b10cks/cli` and `@b10cks/mcp-server` +- Server-side only โ€“ Management API tokens must never reach the browser + +```bash +npm install @b10cks/mgmt-client +``` + ## ๐Ÿš€ Quick Start ### For Nuxt Projects @@ -140,11 +208,13 @@ const blocks = await dataApi.getBlocks() ## ๐Ÿ“– Documentation -- [b10cks Documentation](https://docs.b10cks.com/) -- Individual package READMEs: - - [Client Package](./packages/client/README.md) - - [Vue Package](./packages/vue/README.md) - - [Nuxt Package](./packages/nuxt/README.md) +- [b10cks Documentation](https://www.b10cks.com/docs) +- Individual package READMEs: [client](./packages/client/README.md) ยท + [richtext](./packages/richtext/README.md) ยท [vue](./packages/vue/README.md) ยท + [nuxt](./packages/nuxt/README.md) ยท [react](./packages/react/README.md) ยท + [next](./packages/next/README.md) ยท [svelte](./packages/svelte/README.md) ยท + [mcp-server](./packages/mcp-server/README.md) ยท [cli](./packages/cli/README.md) ยท + [mgmt-client](./packages/mgmt-client/README.md) ## ๐Ÿ› ๏ธ Development @@ -257,14 +327,21 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu MIT โ€“ see [LICENSE](./LICENSE) for details +## ๐Ÿ” Security + +Please report security vulnerabilities privately โ€“ see [SECURITY.md](./SECURITY.md). Do not open a +public issue for them. + ## ๐Ÿ’ฌ Support & Community -- **Discord**: [Join our community](https://discord.gg/coders_cantina) -- **Issues**: [GitHub Issues](https://github.com/b10cks/sdk/issues) +- **Discussions**: [GitHub Discussions](https://github.com/b10cks/sdk/discussions) โ€“ questions, ideas and show & tell +- **Issues**: [GitHub Issues](https://github.com/b10cks/sdk/issues) โ€“ bugs and feature requests +- **Discord**: [Join our community](https://discord.gg/mdcDktFFcp) ## ๐Ÿ”— Links -- [b10cks Website](https://discord.gg/KYWFsctk) +- [b10cks Website](https://www.b10cks.com) +- [b10cks Documentation](https://www.b10cks.com/docs) - [GitHub Repository](https://github.com/b10cks/sdk) - [npm Organization](https://www.npmjs.com/org/b10cks) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..eff2032 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,58 @@ +# Security Policy + +## Reporting a vulnerability + +**Please do not report security vulnerabilities through public GitHub issues, pull requests or +Discord.** + +Report them privately through +[GitHub Security Advisories](https://github.com/b10cks/sdk/security/advisories/new). If you cannot +use that form, email instead. + +Please include as much of the following as you can โ€“ it helps us reproduce and triage faster: + +- The affected package(s) and version(s) +- The type of issue (token leakage, XSS, prototype pollution, supply chain, โ€ฆ) +- Steps to reproduce, ideally a minimal proof of concept +- The impact you believe an attacker could achieve + +## What to expect + +| Stage | Target | +| ----------------------------- | ----------------------------------------------------- | +| Acknowledgement of the report | within 3 business days | +| Initial assessment | within 7 business days | +| Fix released | depends on severity โ€“ critical issues are prioritised | + +We will keep you updated as we work on a fix, and we will credit you in the advisory and release +notes unless you ask us not to. + +Please give us a reasonable window to ship a fix before disclosing the issue publicly. We publish a +GitHub Security Advisory for every confirmed vulnerability once a patched version is available. + +## Scope + +In scope are the packages published from this repository: + +`@b10cks/client`, `@b10cks/mgmt-client`, `@b10cks/cli`, `@b10cks/mcp-server`, `@b10cks/richtext`, +`@b10cks/vue`, `@b10cks/react`, `@b10cks/svelte`, `@b10cks/nuxt`, `@b10cks/next`. + +Only the **latest released version** of each package receives security fixes. Backports to older +majors are considered case by case. + +Vulnerabilities in the b10cks hosted platform or Management API itself are out of scope here โ€“ +report those to or via [b10cks.com](https://www.b10cks.com). + +## Handling access tokens + +Most reports we expect concern credentials, so to set expectations: + +- The **access token** passed to `@b10cks/client` (and therefore to `@b10cks/vue`, `@b10cks/react`, + `@b10cks/svelte`, `@b10cks/nuxt` and `@b10cks/next`) is a **public, read-only Data API token**. It + is shipped to the browser by design โ€“ in Nuxt it lives in `runtimeConfig.public.b10cks`. +- **Management API tokens** (used by `@b10cks/mgmt-client`, `@b10cks/cli` and `@b10cks/mcp-server`) + are privileged and must never reach the browser. The CLI stores them in `~/.netrc` with `0600` + permissions. +- Putting a Management API token into a client-side SDK config is a misconfiguration, not a + vulnerability in these packages. A path by which a _public_ token grants write access, or by which + a _management_ token is exposed by our code, absolutely is โ€“ please report it.