Skip to content

Extend the plugins' isolation surface area#22

Merged
lyssieth merged 6 commits into
mainfrom
feat/extend-plugin-isolation-surface-area
Jun 6, 2026
Merged

Extend the plugins' isolation surface area#22
lyssieth merged 6 commits into
mainfrom
feat/extend-plugin-isolation-surface-area

Conversation

@lyssieth

@lyssieth lyssieth commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Expands the surface area of what we (currently pretend to) isolate (so in the future we can actually do it) to a few new fields.

Filesystem, and critically due to the GitHub plugin, cryptography.
SDK + Plugins require a version bump due to this too. Publishing once PR is merged.

lyssieth added 6 commits June 6, 2026 05:04
Add pemToDer, base64urlEncode, and base64urlDecode helpers for use
by plugins that need to strip PEM armor or encode/decode base64url.
Supports PKCS#8, PKCS#1, SEC1, SPKI, and certificate PEM headers.
…olContext

New types:
- WebCryptoFormat  — normalized key format for Web Crypto import
- FsStat           — stat result (size, type, timestamps)
- FsDirent         — directory entry (name, type)
- FsApi            — sandbox-aware filesystem interface

PluginToolContext gains crypto.loadNormalizedKey and fs (readTextFile,
writeTextFile, stat, listDir). These bridge the sandbox boundary
through RPC for plugin workers or directly for the engine context.
Engine ctx:
- crypto.loadNormalizedKey: normalize PEM/DER key to PKCS#8/SPKI
  using node:crypto, reading via sandbox path or inline data
- fs.readTextFile / writeTextFile / stat / listDir: sandbox-aware
  filesystem access with mount mapping and conditional access checks

Plugin worker RPC:
- Forward crypto.loadNormalizedKey, fs.*, paths.* calls from worker
  to runtime via RpcChannel handlers
- worker-main.ts buildCtx creates stubs that proxy through RPC
…edKey

Replace manual PEM resolution and Node crypto.createPrivateKey/sign
with ctx.crypto.loadNormalizedKey (auto-detects PKCS#1/PKCS#8/SEC1)
and SDK base64urlEncode. JWT signing now uses Web Crypto via the
runtime's normalized key, removing the direct dependency on fs and
crypto module internals from plugin code.
SDK 0.5.0 adds:
- WebCryptoFormat, FsStat, FsDirent, FsApi types
- crypto.loadNormalizedKey and fs on PluginToolContext
- pemToDer, base64urlEncode, base64urlDecode utilities

All plugins with peerDependency on @cireilclaw/sdk updated to ^0.5.0
Add crypto.loadNormalizedKey to the PluginToolContext interface and
its note. List new SDK exports (pemToDer, base64urlEncode,
base64urlDecode) in the SDK exports section.
@lyssieth lyssieth self-assigned this Jun 6, 2026
@lyssieth lyssieth added the enhancement New feature or request label Jun 6, 2026
@coderabbitai

coderabbitai Bot commented Jun 6, 2026

Copy link
Copy Markdown

PR changed again? Review this PR in Change Stack to compare snapshots and stay oriented.

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e462535f-6200-4f00-9310-4aa701632d8a

📥 Commits

Reviewing files that changed from the base of the PR and between 0de9afd and 3fcd39e.

📒 Files selected for processing (13)
  • docs/plugins/developers.md
  • packages/brave-search/package.json
  • packages/openweather/package.json
  • packages/plugin-github/package.json
  • packages/plugin-github/src/auth.ts
  • packages/runtime/src/engine/index.ts
  • packages/runtime/src/plugin/loader.ts
  • packages/runtime/src/plugin/worker-main.ts
  • packages/sdk/package.json
  • packages/sdk/src/encoding.ts
  • packages/sdk/src/index.ts
  • packages/sdk/src/tool.ts
  • packages/template/package.json

📝 Walkthrough

Walkthrough

This PR extends the plugin runtime with WebCrypto-based key normalization and sandboxed filesystem operations. The SDK defines types and encoding utilities; the runtime implements RPC handlers for crypto and filesystem access with access control; workers expose these as plugin APIs; the GitHub plugin refactors JWT signing to use the new async crypto; and all dependencies are updated.

Changes

Plugin crypto and filesystem capabilities

Layer / File(s) Summary
SDK type contracts and encoding utilities
packages/sdk/src/tool.ts, packages/sdk/src/encoding.ts, packages/sdk/src/index.ts, packages/sdk/package.json
WebCryptoFormat, FsApi, FsDirent, FsStat types define the plugin tool context contract; pemToDer and base64url encode/decode utilities enable key format conversion; version bumped to 0.5.0.
Runtime RPC handlers for crypto and filesystem
packages/runtime/src/plugin/loader.ts, packages/runtime/src/engine/index.ts
Engine and loader register RPC handlers for key normalization (crypto.loadNormalizedKey) and sandboxed filesystem ops (readTextFile, writeTextFile, stat, listDir), enforcing path resolution and access control.
Worker context building for plugin access
packages/runtime/src/plugin/worker-main.ts
buildCtx exposes RPC-backed crypto and fs APIs to plugin code, forwarding method calls to corresponding RPC handlers.
GitHub plugin JWT signing refactor
packages/plugin-github/src/auth.ts, packages/plugin-github/package.json
JWT generation switches from synchronous Node crypto to async WebCrypto flow using ctx.crypto.loadNormalizedKey and SDK utilities; generateJWT becomes async and uses crypto.subtle.sign for RS256 signing.
Package version and dependency updates
packages/brave-search/package.json, packages/openweather/package.json, packages/template/package.json
Peer and dev dependencies on @cireilclaw/sdk updated to ^0.5.0 across plugin packages.
Developer guide documentation
docs/plugins/developers.md
Documentation extended to include crypto.loadNormalizedKey, filesystem methods (readTextFile, writeTextFile, stat, listDir), and SDK exports (pemToDer, base64urlEncode, base64urlDecode).

Possibly related PRs

  • CutieZone/CireilClaw#19: Refactors the GitHub plugin auth to use WebCrypto-based JWT signing with the new ctx.crypto.loadNormalizedKey and SDK encoding utilities.
🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the primary objective of the PR: extending the plugins' isolation surface area with new crypto and filesystem capabilities.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.


Comment @coderabbitai help to get the list of available commands and usage tips.

@lyssieth lyssieth merged commit 2393b48 into main Jun 6, 2026
7 checks passed
@lyssieth lyssieth deleted the feat/extend-plugin-isolation-surface-area branch June 6, 2026 02:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant