Skip to content

docs: reframe root README as monorepo #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryanbas21 merged 1 commit into from
May 12, 2026
Merged

docs: reframe root README as monorepo #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
149 changes: 98 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,38 @@
# WolfCola DevTools

**Captures, correlates, and diagnoses** OIDC/OAuth 2.0 authentication flows in real time — works standalone with any OIDC provider or as an enhanced companion to the Ping Identity SDK.

Available as a **browser DevTools panel** (Chrome & Firefox) and a **VS Code extension** (via Chrome DevTools Protocol). Both share the same annotation engine, diagnosis rules, and Elm UI.

![Flow view with diagnosis banner and node rail](packages/devtools-extension/screenshots/Flow-Screen.png)
A monorepo of developer tools — OIDC/OAuth 2.0 diagnostics, tree-shaking analysis, and more. Built with TypeScript, Effect, and pnpm workspaces.

---

## Packages

| Package | Description | npm |
| --- | --- | --- |
| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private |
| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private |
| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private |
| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private |
| [`devtools-bridge`](packages/devtools-bridge) | SDK adapter — emits events from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) |
| [`devtools-types`](packages/devtools-types) | Effect Schema definitions for AuthEvent, FlowState | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) |
### OIDC DevTools

Captures, correlates, and diagnoses OIDC/OAuth 2.0 authentication flows in real time — works standalone with any OIDC provider or as an enhanced companion to the Ping Identity SDK. Available as a browser DevTools panel and a VS Code extension.

| Package | Description | npm |
| --------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private |
| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private |
| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private |
| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private |
| [`devtools-bridge`](packages/devtools-bridge) | SDK adapter — emits events from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) |
| [`devtools-types`](packages/devtools-types) | Effect Schema definitions for AuthEvent, FlowState | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) |

### Tree-shaking tools

Analyze and enforce tree-shakeability across your packages — catch bundle-bloating patterns at authoring time and verify the result post-build.

| Package | Description | npm |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [`treeshake-check`](packages/treeshake-check) | CLI & library — checks whether a package can be fully tree-shaken by Rollup | [![npm](https://img.shields.io/npm/v/@wolfcola/treeshake-check)](https://www.npmjs.com/package/@wolfcola/treeshake-check) |
| [`eslint-plugin-treeshake`](packages/eslint-plugin-treeshake) | ESLint plugin that flags code patterns known to break tree-shaking | [![npm](https://img.shields.io/npm/v/@wolfcola/eslint-plugin-treeshake)](https://www.npmjs.com/package/@wolfcola/eslint-plugin-treeshake) |

---

## Quick start

### Browser extension
### OIDC browser extension

```bash
pnpm install
Expand All @@ -33,7 +42,7 @@ pnpm build:firefox # Firefox

Load the extension as unpacked from `packages/devtools-extension/dist/` — see the [extension README](packages/devtools-extension) for full instructions.

### VS Code extension
### OIDC VS Code extension

```bash
pnpm install
Expand All @@ -56,16 +65,38 @@ In the VS Code window, run `Ctrl+Shift+P` → **"OIDC DevTools: Start Capture"**

See the [VS Code extension README](packages/vscode-extension) for detailed setup, troubleshooting, and the mock OIDC server for testing.

### Browser compatibility
### Tree-shake check

| Browser | Minimum version |
| --- | --- |
| Chrome | 88+ (Manifest V3) |
```bash
pnpm add -D @wolfcola/treeshake-check
pnpm treeshake-check
```

### ESLint plugin

```bash
pnpm add -D @wolfcola/eslint-plugin-treeshake
```

```js
// eslint.config.mjs
import treeshake from '@wolfcola/eslint-plugin-treeshake';

export default [treeshake.configs.recommended];
```

See each package README for full usage and configuration.

### Browser compatibility (OIDC extension)

| Browser | Minimum version |
| ------- | -------------------------------------- |
| Chrome | 88+ (Manifest V3) |
| Firefox | 128+ (`world: "MAIN"` content scripts) |

### SDK integration (optional)

The extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge:
The OIDC extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge:

```bash
pnpm add @wolfcola/devtools-bridge
Expand All @@ -85,6 +116,8 @@ The bridge is a no-op when the extension is not installed.

## Architecture

### OIDC DevTools

```
┌──────────────────────────────────────────────────────────┐
│ Shared Packages │
Expand All @@ -110,26 +143,40 @@ Both consumers import the same annotators, diagnosis engine, and Elm UI from the
- **Browser extension** → `chrome.devtools.network.onRequestFinished` + content script relay
- **VS Code extension** → CDP `Network` domain + `Runtime.bindingCalled` for SDK events

### Tree-shaking tools

```
┌───────────────────────────┐ ┌──────────────────────────────┐
│ eslint-plugin-treeshake │ │ treeshake-check │
│ │ │ │
│ Per-file AST checks │───▶│ Full Rollup bundle build │
│ Fast, heuristic │opt │ Ground-truth analysis │
│ Editor squiggles + fix │ │ CLI + exit codes for CI │
└───────────────────────────┘ └──────────────────────────────┘
```

The ESLint plugin provides fast, per-file feedback during development. `treeshake-check` runs a full Rollup build for ground-truth verification in CI. When `bundleCheck: true` is set in the ESLint plugin, it delegates to `treeshake-check` and maps results back to source locations.

---

## Network-first OIDC intelligence

The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without any SDK integration. It works out of the box with **any OIDC provider** — Ping Identity, Auth0, Okta, Keycloak, or any spec-compliant authorization server.
The OIDC extension automatically detects and annotates OIDC/OAuth 2.0 traffic without any SDK integration. It works out of the box with **any OIDC provider** — Ping Identity, Auth0, Okta, Keycloak, or any spec-compliant authorization server.

**Well-known discovery** — parses `/.well-known/openid-configuration` responses and matches subsequent requests against discovered endpoints.

**OIDC semantic annotation:**

| Phase | Extracted data |
| --- | --- |
| **discovery** | Issuer, all discovered endpoints |
| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` |
| **par** | `request_uri`, `expires_in`, pushed parameters |
| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` |
| **userinfo** | User profile data |
| **revocation** | Token revocation status |
| **introspection** | Token validity |
| **end-session** | Logout status |
| Phase | Extracted data |
| ----------------- | ---------------------------------------------------------------- |
| **discovery** | Issuer, all discovered endpoints |
| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` |
| **par** | `request_uri`, `expires_in`, pushed parameters |
| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` |
| **userinfo** | User profile data |
| **revocation** | Token revocation status |
| **introspection** | Token validity |
| **end-session** | Logout status |

**DPoP detection (RFC 9449)** — detects `DPoP` proof JWTs, `token_type: "DPoP"`, `use_dpop_nonce` errors, and `DPoP-Nonce` headers.

Expand All @@ -141,15 +188,15 @@ The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without

Every captured event is run through a rule engine that produces flow-level and per-event diagnostics with severity ratings and numbered remediation steps.

| Category | Examples |
| --- | --- |
| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials |
| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs |
| **Flow config** | Node error/failure status, connector errors, policy-not-found |
| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch |
| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse |
| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch |
| **PAR** | Missing `request_uri`, inline params alongside `request_uri` |
| Category | Examples |
| --------------- | ----------------------------------------------------------------------------------- |
| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials |
| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs |
| **Flow config** | Node error/failure status, connector errors, policy-not-found |
| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch |
| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse |
| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch |
| **PAR** | Missing `request_uri`, inline params alongside `request_uri` |

---

Expand All @@ -174,20 +221,20 @@ Canvas-based flow lifecycle visualization with layout variants for DaVinci, Jour
```bash
pnpm install
pnpm build # build all packages
pnpm test # vitest (308 tests)
pnpm test # vitest
pnpm typecheck # TypeScript type checking
pnpm lint # eslint
```

| Script | Description |
| --- | --- |
| `pnpm build` | Build all packages |
| `pnpm test` | Run all unit tests |
| `pnpm typecheck` | TypeScript type checking |
| `pnpm lint` | Lint all packages |
| `pnpm changeset` | Create a changeset for versioning |
| `pnpm version` | Apply changesets and bump versions |
| `pnpm release` | Build and publish to npm |
| Script | Description |
| ---------------- | ---------------------------------- |
| `pnpm build` | Build all packages |
| `pnpm test` | Run all unit tests |
| `pnpm typecheck` | TypeScript type checking |
| `pnpm lint` | Lint all packages |
| `pnpm changeset` | Create a changeset for versioning |
| `pnpm version` | Apply changesets and bump versions |
| `pnpm release` | Build and publish to npm |

### Tech stack

Expand All @@ -202,7 +249,7 @@ pnpm lint # eslint

## Security and privacy

The extension requests only `storage` and `clipboardWrite`/`clipboardRead` — no `cookies`, `webRequest`, `tabs`, or other sensitive APIs. Content scripts use a two-world architecture to prevent arbitrary page code from injecting messages into the background script. All SDK events are decoded through `AuthEventSchema` (Effect Schema) before reaching the EventStore — malformed payloads are dropped. Captured data is stored locally and never transmitted off-device.
The OIDC extension requests only `storage` and `clipboardWrite`/`clipboardRead` — no `cookies`, `webRequest`, `tabs`, or other sensitive APIs. Content scripts use a two-world architecture to prevent arbitrary page code from injecting messages into the background script. All SDK events are decoded through `AuthEventSchema` (Effect Schema) before reaching the EventStore — malformed payloads are dropped. Captured data is stored locally and never transmitted off-device.

---

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "wolfcola-devtools",
"version": "0.0.0",
"private": true,
"description": "WolfCola DevTools — Chrome extension and SDK bridges",
"description": "WolfCola DevTools — OIDC diagnostics, tree-shaking analysis, and developer tools",
"license": "MIT",
"repository": {
"type": "git",
Expand Down
Loading