2 commits

Author	SHA1	Message	Date
Adam Moussa	faa497de73	docs: repoint pending cross_reviewer follow-ups to security-review cross_review.py (#30)	2026-07-14 19:24:12 -04:00
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>	2026-06-26 12:47:04 -04:00