mirror of
https://github.com/Sea-Haven-Industries/sh-mcp.git
synced 2026-09-30 14:43:17 +00:00
4 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Adam Moussa
|
a722d62f02
|
docs: add sh-mcp-auth deploy runbook (#5)
Some checks failed
deploy / deploy (push) Has been cancelled
First-time deploy procedure for the Phase 2a Cognito auth substrate: the five one-time prerequisites (CDK bootstrap, the two Google secrets with exact JSON shapes, the githubdeploy-sh-mcp OIDC role, the managed Google Groups), the synth → diff → watched manual first deploy → CD hand-off flow, post-deploy validation (ESSENTIALS + V2 trigger, finance client ceiling, group-sync run, deny-list hard-revocation smoke test), and rollback/teardown (RETAIN tables; 0a spike teardown deferred until sh-mcp-auth is validated). Notes that CD (deploy.yaml) is already wired and red on every merge until the OIDC deploy role exists, and that no Cognito hosted-UI domain ships in 2a (OAuth code flow deferred to 2b surface wiring). |
||
|
Adam Moussa
|
a28e22bb91
|
Add Agentforce migration & architecture plan (#1)
* Add Agentforce migration & architecture plan Decision document mapping the sh-mcp design.md substrate onto Agentforce: 3-agent roster (Ops/Finance/Lauren Exec) on trust-tiered MCP servers, per-user OAuth via Cognito, Data Library/retriever design replacing the Bedrock KB, model/DX/Testing-Center plans, cutover phasing, and an 11-item capability-gap register. https://claude.ai/code/session_01BvKGBQ4ek6JRZVkFicZuw6 * Resolve open decisions: per-user auth pattern + reasoning model Fold Adam's decisions and deep-research (wf_1bf9e142) outcomes into the plan: - D4: ES/Apex actions + Per-User OAuth Browser Flow External Credential -> Cognito; native remote-MCP connector off the per-user hop (Beta, per-user binding unconfirmed). - D5: AWS-Hosted Claude as the planner; BYOLLM ruled out (custom-action-only, routes through SF Models API/Trust Layer). Guardrail moves to the MCP/action layer (revises D11). - D1 accepted; D3 accepted; G8 corpus authoring deferred (fund when needed). - Resolve gaps G1/G2/G6; add §0.1 resolutions and a Phase-0 verify-in-org gate. * Add D12: OpenAPI-first, MCP-ready transport-agnostic core Tool handlers + shared auth/scope/PII/audit guard built independent of wire protocol; OpenAPI adapter shipped now (Agentforce External Service actions, Apex only for shaping); MCP adapter deferred to a named trigger (real IDE/Claude Code workflow, or native remote-MCP per-user GA). Update decision log, §0.1 transport architecture block, §1h test split (OpenAPI contract now, MCP conformance deferred), and §4 deliverables (annotate design.md §4; transport-agnostic core story). * Remediate sh-plan-review findings (B1-B5, F1-F7, NITs, Qs) Address the Fable plan-review gate (REQUEST CHANGES): - B1: move ALL teardown to Phase 4 + shared-consumer audit; notion-sync dual-feeds; rollback never targets a deleted/starved resource. - B2: propagate the §0.1 resolutions through D5/D11/§1d/§2.x/§3/G6/G9/§6 (model, guardrail, dropped ~30% claim, Phase-0 'verify' not 'decide'). - B3: pin D12 to one facade per trust tier (per-server Cognito audience at the edge); reconcile the §1h list_tools test (deferred with MCP adapter). - B4: specify per-agent External Credential + Cognito app client minting only its tier's scopes; add the token-layer trifecta test. - B5: split Phase 0 (0a auth spike gates 0b); add custom-Bolt fallback; relabel G1 as mitigation-chosen/unverified. - F1-F7: Testing-Center identity (G12); design.md amendments reframed (F2); sh-agentforce new-repo checklist + cd-sfdx JWT-key auth (F3); platform-build phase (F4); Salesforce data-processor gap (G13/F5); memory+README obligations (F6); per-user visibility degradation (G14/F7). - NITs: S3->Data Cloud ingestion pinned; facade+notion-sync ALARM monitoring; DevName naming boundary. Qs Q1-Q3 registered as G15 + verify items. - §0.3 remediation log + gap count 11->15. * Fold in cross_reviewer (GPT-4.1) auth/trifecta findings Cross-family review caught defense-in-depth gaps: - CR-1: validate aud at edge AND server-side (per-tier authorizer doesn't replace design.md §2.5 server enforcement); alarm on wrong-audience tokens. - CR-6: finance-audience token must not reach Gmail/Calendar even with a Google token. - CR-2: verify+enforce received sub is the Google Workspace sub, not a Salesforce id. - CR-3: pre-token Lambda fails closed on cross-audience scope. - CR-5: pre-token + group-sync are the auth SPOF — alarms + group-claim freshness bound. - CR-4/CR-7: restrict per-client Cognito scopes; WAF is defense-in-depth only. Reflected in §0.1 B3/B4, §1h tests, §4 monitoring, §5 cross-review log. * Remediate Fable round-2: BLOCK-1 credential mechanism + residual fixes - BLOCK-1: invert the token-layer trifecta layering — per-app-client AllowedOAuthScopes is the PRIMARY vendor-supported boundary (Cognito won't issue out-of-tier scopes regardless of group union); pre-token suppression is a fail-closed backstop; the aud/authorizer mechanism is flagged unverified-load-bearing and added to the §6 verify gate (#8); fix the design.md §2.3 misattribution + add the amendment to §4. - FIX-1: §1f notion-sync dual-feeds via S3 (was 'repointed instead of'). - FIX-2: split Phase 0a exit gate into fatal vs decision-input (Testing-Center identity). - FIX-3: remove stale 'boundary stays in infrastructure' phrasing (server is the boundary). - FIX-4: bound parallel-run double-spend (G9 + Phases 1-3 time-box). - FIX-5: specify minimal throwaway 0a kit + Slack-plan dependency. - FIX-6: remove dangling (O3); D3 recorded as accepted. - NITs: severity arithmetic, Ops welcome no longer oversells tasks, wrong-audience alarm named, flip-point clarified. Q1 fallback scope + Q2 freshness-bound documented. * Fold in Gemini (round-3, third model family) auth findings - Gemini-BLOCK-1: AllowedOAuthScopes strictly filtering a V2 pre-token Lambda's output is unverified -> fatal Phase-0a check (§6 #8a); if it fails, pre-token fail-closed becomes the primary boundary. - Gemini-BLOCK-2: Cognito access tokens carry client_id/scopes, not native aud -> align §1h + facade/server checks to client_id allow-list / scope-prefix audience proxy. - Gemini-Q: 0a spike must run on production-equivalent Enterprise Grid + real licenses. - Gemini-NIT (path-corrected): project memory is a private store at ~/.claude/.../memory/, not the repo and not Gemini's own ~/.gemini path. Three model families now converge: structural plan sound; only open risk is the auth token-mint mechanism, fully spike-gated in Phase 0a. * Fold in Gemini round-4 CI/CD + decoupling findings (with corrections) - ARM64 markers (enable-qemu both files + platform:LINUX_ARM64) for Docker-bundled tier tasks -> Phase 0b build + exit (per reference_cicd_arm64_qemu). - Node 24 / workflows: sh-agentforce keeps thin ci.yaml/deploy.yaml callers but they call the new cd-sfdx, NOT the AWS CDK templates (corrected the reviewer's framing). - CR-1 decoupling: client/audience matrix injected as config (SSM/CDK env), not hardcoded into the transport-agnostic core; corrected reviewer's 'Secrets Manager' -> SSM (client_ids are non-sensitive). §6 #8d. - Role isolation: new isolated githubdeploy-sh-agentforce (never reuse sh-mcp role), scoped only to read the JWT secret since deploy target is Salesforce not AWS. Reviewer applied AWS/CDK conventions to a Salesforce-deploying repo; folded in with corrections. * Fold in Phase-0a research findings (wf_3e88d8a8) — design changes + new top risk Research resolved the doc-answerable 0a unknowns before the live spike: - Finding 1: AllowedOAuthScopes does NOT cap a pre-token V2 Lambda's scopesToAdd -> redesign to a SUPPRESS-ONLY Lambda (keeps AllowedOAuthScopes as the real per-tier ceiling). - Finding 2: V2 needs Essentials plan (default; Lite ignores it) — negligible cost. - Finding 3: Cognito access tokens carry client_id/scopes, no aud -> client_id allow-list + scope-prefix as the audience proxy (resolves the §8c unknown). - Finding 4 (NEW CRITICAL G16, now THE top risk): Employee-Agent callouts may carry SERVICE identity, not the user's -> 0a fatal #1; fallbacks MuleSoft RFC 8693 / signed header / Bolt. - Finding 5: per-user actions UNTESTABLE via batch Testing Center -> scripted interactive parity sessions (G12 resolved). - Finding 6: all-staff agent not free (Flex Credits / $125-user add-on) -> G9 cost model. - Finding 7: model_config may allow BYOLLM as a per-agent planner -> reopen as verify (upside). Added §0.4 findings record; gap count 15->16; verify items reordered (G16 = fatal #1). --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Adam Moussa
|
0d1fefb326
|
Phase 0b slice: monorepo scaffold + @sh-mcp/shared core + integration packages (#2)
Some checks are pending
deploy / deploy (push) Waiting to run
* Phase 0b slice: monorepo scaffold + shared core + integration packages The 0a-INDEPENDENT code slice (one-shot via af-0b-package-slice workflow: Haiku scaffold + Sonnet packages, Sonnet fix-to-green). Nothing deploys; no CDK/servers. - Monorepo scaffold: npm workspaces, strict TS (NodeNext), vitest (80% gate), eslint 9 flat config, prettier; ci.yaml/deploy.yaml callers (Node 24, enable-qemu). - @sh-mcp/shared: transport-agnostic core — Scope/AuthContext/ToolDef, ToolRegistry, redact()+maskValue() (PII), OpenAPI 3.1 generator. AUTH STUBBED behind an AuthProvider interface (TODO auth-layer-0a); JWT/aud/client_id/JWKS/deny-list deferred per design.md §2. - 9 integration packages (qbo, google-maps, internal-data, payments, knowledge-base, gmail, calendar, tasks, reminders): tools against shared, external deps mocked behind injected client interfaces; finance handlers call redact(). Verified green: tsc -b clean, vitest 245/245, eslint 0 errors. Auth mechanism intentionally deferred until the 0a spike resolves it (G16/§0.4). * Complete Cognito auth provider + Phase 1 build brief Finish the WIP CognitoAuthProvider (client_id allow-list as audience boundary, finance TTL ceiling, deny-list, scope-prefix stripping) with its test suite, and check in docs/build-plan-phase-1.md so the Phase 1 work has its governing brief in-tree (design.md §2.5). * ci: disable cdk synth for Phase 0b (no CDK app yet) The reusable ci-typescript-cdk workflow defaults run-cdk-synth: true, but the Phase 0b package scaffold has no cdk.json or stacks, so cdk synth fails with '--app is required'. Disable it here; Phase 1 re-enables it with the server CDK stubs. |
||
| 3e2d99a1eb |
Initial commit: sh-mcp design and plan
Design doc for the Sea Haven MCP platform that replaces seahaven-slack-bot and exec-aide: trust-tiered MCP servers, Google-SSO via a Cognito broker, TypeScript monorepo. Cross-review (cross_reviewer/GPT-4.1) folded in. Status: planning only, nothing built. |
