docs: ADRs, governance, and community foundation - #17
Merged
Conversation
…tensibility Five ADRs documenting the major architecture decisions: - 0001: Three-mode auth (dev, standalone OIDC, federated proxy) - 0002: npm package consumption model (mod-arch-core pattern) - 0003: Proxy-delegated auth BFF pattern (dumb pipe for tokens) - 0004: Self-contained page components for downstream reuse - 0005: Federated credential bridge gap (open/unresolved) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Step-by-step instructions for integrating the OpenShell Dashboard into odh-dashboard via module federation, including webpack config, wrapper components, extension registration, BFF proxy, and auth. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New ADRs capturing established architecture decisions: - 0006: Standalone upstream repo (community-first, not embedded) - 0007: Proto files as source of truth (no invented APIs) - 0008: Polling not WebSockets (federation proxy constraint) - 0009: Sandbox-centric object model (no Agent abstraction) Updated ADR 0005 with Praxis/AI Gateway research (Option D) and gateway OIDC role mapping details from ACP team's verified deployment. Community governance files: - LICENSE (Apache 2.0) - CONTRIBUTING.md (DCO, conventional commits, AI policy, dev setup) - CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - SECURITY.md (vulnerability reporting) - CODEOWNERS Updated CLAUDE.md to link architecture rules to their ADRs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Gkrumbach07
changed the title
Audit found critical inaccuracies that would cause agents to produce wrong code. Fixed: CLAUDE.md: - Project structure now lists hooks/, slots/, utils/, models/, scripts/ - RPC count corrected to 68 (64 + 4) - Removed stale "~30 RPCs" claim bff-go.md: - Removed nonexistent middleware.go from directory tree - Added missing gateway files (logs.go, services.go, interface.go) - Added models/ package documentation - Fixed generated type packages (datamodelv1, openshellv1 etc, not pb) - Added handler pattern with decodeBody/writeGrpcError/models.From*() - Updated config table (OIDC vars are env-only, added missing entries) - Added Interface/mock documentation security.md: - Fixed token storage: JS memory via authStore.ts, not HTTP-only cookies - Added references to specific helper functions (writeGrpcError, etc) - Added models.FromProvider() credential stripping detail add-rpc skill (most impactful fix): - Fixed handler names (no Handler suffix) - Fixed error handling (writeGrpcError, not app.handleGRPCError) - Fixed response pattern (writeJSON + models.From*(), not app.writeJSON) - Fixed body decoding (decodeBody, not json.Decode) - Fixed frontend API functions (post/get/del, not restCREATE) - Added missing steps: Interface update, models DTO, queryKeys, test mock add-page skill: - Fixed page paths (flat in src/pages/, no subdirectories) - Fixed route file (App.tsx, not AppRoutes.tsx) - Fixed imports (relative, not ~/ alias) - Fixed nav file reference (AppLayout.tsx) - Fixed verify commands to use make targets react.md: - Corrected import convention (relative, not ~/) - Added queryKeys pattern for React Query - Added client.ts function names (get, post, put, del) - Added hooks/ directory mention dev-workflow skill: - Replaced brain/ planning doc paths with in-repo references - Added Prettier format check to verify steps Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CLAUDE.md: note oidc/ subdir under src/app/, add make dev-full target - bff-go.md: add defaults for ADMIN_ROLE and LOGOUT_URL, add missing env-only vars (OIDC_SCOPES, OIDC_USER_ROLE, DEPLOYMENT_CONTEXT, FEATURE_* flags), clarify OIDC handler route paths Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add missing optionsv1/ to gen/ directory listings (CLAUDE.md, bff-go.md) - Add observability.go to models/ listing (bff-go.md) - Fix add-rpc: request structs go in handler file (simple) or models/builders.go (complex), not always models/ - Fix add-rpc: workspaceKeys uses .all not .list() (no list() method) - Fix add-page: routes go in AuthenticatedApp component, not AppRoutes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
authStore.ts uses window.sessionStorage, which survives page reloads and is accessible to same-origin scripts. The previous description said "JavaScript memory" which implies a module-scoped variable lost on reload — a meaningful distinction for security threat modeling. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…extension surface Rewrites the auth ADRs to match post-#24 reality and adds three new ADRs that take firm architectural stances: - ADR 0001 v2: auth described as modes (dev/standalone/federated) x patterns (token relay / session custodian / future token exchange), replacing the conflated 'three-mode' framing - ADR 0003 v2: 'token custody, not token validation' replaces the no-longer- accurate 'dumb pipe' doctrine; the custody/validation line is the boundary - ADR 0005: adds Aug 6-7 #team-openshell outcomes (standalone-first, shared OIDC recommended, own-flow vs token-exchange mechanisms) - ADR 0008 v2: polling for data, WebSocket for the terminal only — reconciles the ADR with the shipped terminal relay - ADR 0011 (new): BFF scope boundary — four jobs, an explicit never-list, and rulings on previously ambiguous proposals - ADR 0012 (new): the extension surface — five downstream mechanisms (barrels, slots, callbacks, flags, runtime config) and the zero-CSS policy - ADR 0013 (new, Proposed): adopt openshell-sdk-go (PR #2) with provenance, parity, and secret-hygiene conditions CLAUDE.md and .claude rules updated to match (cookie sessions replace the stale sessionStorage guidance; bearer precedence chain; scope never-list). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5 tasks
The BFF never terminates authentication — a fronting auth proxy (oauth2-proxy standalone, kube-auth-proxy federated) owns login, sessions, refresh, and CSRF in every authenticated deployment. Implementation in PR #29 (-2,000 lines). - ADR 0014 (new): relay-only decision; supersedes ADR 0010. Standalone and federated become the same architecture with different proxy operators; documents the proxy-is-the-only-path deployment invariant - ADR 0010: marked Superseded — its requirements were right, oauth2-proxy meets them on the other side of a network boundary - ADR 0001 v3: pattern space collapses to token relay; the only auth switch left is AUTH_DISABLED - ADR 0003 v3: 'the BFF is a token relay' — the dumb-pipe doctrine is true again, with the drift history recorded - ADR 0011 v2: three jobs (custody removed); never-list gains 'no auth termination' - ADR 0005/0008/0012: consistency edits (embedding mechanism = dedicated proxy flow; WS upgrade auth via proxy; dead flags/slot removed in #29) CLAUDE.md and .claude rules updated to relay-only reality. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Numbering reset while pre-1.0 and unmerged — no supersession chains, no version suffixes. The auth trilogy (modes/patterns, token relay, relay-only decision) collapses into ADR 0003 with a History section preserving the sessionStorage → cookie-custodian → relay-only path and its lesson. Self-contained pages folds into the extension surface (ADR 0005 §3). Final roster: 0001 standalone repo, 0002 npm, 0003 relay-only auth, 0004 scope boundary, 0005 extension surface, 0006 proto truth, 0007 sandbox-centric, 0008 polling+terminal, 0009 credential bridge (Open), 0010 SDK (Proposed). docs/adrs/README.md is the index; append-only from here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Per review: the repo doesn't need an ADR explaining its own existence (folded into 0001's context), proto-vs-SDK mechanics don't deserve a principle doc (0005 is now the SDK-agnostic 'surface the API as-is', absorbing the sandbox-centric object model — same principle, different altitude), the polling/WebSocket stance is one paragraph of the scope boundary plus the FEATURE_TERMINAL flag, and the undecided credential bridge is a design note, not a decision record. Final: 0001 standalone repo + npm, 0002 relay-only auth, 0003 scope boundary, 0004 extension surface, 0005 surface-the-API-as-is, 0006 SDK over stubs (Proposed). docs/design/federated-credential-bridge.md holds the open federated-auth question until it's decided. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
….claude/worktrees Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove all downstream product references — the upstream decision record describes consumers generically (host platform, downstream consumer, fronting auth proxy). Delete docs/design/federated-credential-bridge.md: open questions get an ADR when a decision exists, not before. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Merge the npm-delivery decision and the extension surface into one ADR: how consumers get the code (npm, vs subtree/monorepo) and exactly what they may rely on (barrels, slots, self-contained pages w/ callbacks, feature flags, runtime config; zero co-located CSS). Repo-identity positioning removed — where the repo lives is not a decision consumers depend on. Final five: 0001 downstream consumption, 0002 relay-only auth, 0003 BFF scope boundary, 0004 surface-the-API-as-is, 0005 SDK over stubs (Proposed). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Remove ephemeral references (PR numbers, issue links, person names in rationale, dated audits) from all ADRs. Collapse ADRs 0003-0005 into a single 0003 (SDK adoption). Update project rules and CLAUDE.md to match current codebase state. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Resolve merge conflict in README (keep main's oauth2-proxy config) - Fix lint target description: golangci-lint + prettier, not go vet - Clarify WebSockets are terminal-only, polling is for status - ADR 0001: CSS policy "none" → "minimal" (two small CSS files exist) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- CLAUDE.md: remove phantom "oidc/ subdir" from project structure - CONTRIBUTING.md: lint is golangci-lint not go vet - CONTRIBUTING.md: ADR 0007 reference → .claude/rules/openshell-api.md - security.md: remove CORS claim (no CORS middleware exists) - bff-go.md: remove ALLOWED_ORIGINS (removed in PR #29) - FEATURE_FLAGS.md: remove stale implementation TODOs (all done) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two small CSS files exist (SandboxCard.css, SandboxEgressSummary.css) using PF design tokens for all values. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Five ADRs plus community governance files. Tightened from earlier drafts per review: the repo doesn't need an ADR explaining its own existence, principle docs don't duplicate each other, and open questions live in
docs/design/, not the decision record.docs/adrs/README.mdis the index; append-only from here.The stances
Also
Follow-up issue backlog (to be filed)
npm publishability fixes, CSS policy execution (salvage PR #25 CSS deletions; close #26/#28), slot table-view parity, page navigation-contract holes, barrel/doc gaps, SDK conditions for PR #2, one-command oauth2-proxy compose profile.
Test plan
🤖 Generated with Claude Code