RFC: Rework PR #24 (delegate) into split series aligned with product vision

[amjad-fatmi]

Proposal: Rework the existing closed PR #24 into three smaller, reviewable changes aligned with the Product Constitution and governance boundaries.\n\nGoals:\n- Keep product UX and daemon control-plane boundaries intact (no open, unauthenticated mutation routes on metrics mux).\n- Provide persistent, auditable delegation store (SQLite) for grants before adding transport surface.\n- Ensure transport surface follows existing SDK/admin authentication patterns (standing-admin-token / policy-admin-token), not new unauthenticated HTTP endpoints on metrics port.\n\nPlanned split PRs:\n1) — core delegation model + persistent store (SQLite) + comprehensive unit tests + DB migrations + docs. Acceptance: on-disk persistence in , unit tests for Issue/Verify/Revoke/Chain, no daemon route changes.\n2) — authenticated transport wiring: SDK socket and/or MCP gateway integration, using or existing patterns, not metrics mux. Acceptance: routes only behind admin token, integration tests that exercise signed tokens + auth.\n3) — CLI surface (Create, inspect, verify, and revoke delegation tokens that allow one agent
to act on behalf of another within a governed chain of trust.

Usage:
faramesh delegate [command]

Available Commands:
chain Show the full delegation chain for an agent
grant Grant delegation from one agent to another
inspect Inspect a delegation token's metadata
list List delegations for an agent
revoke Revoke delegation between two agents
verify Verify whether a delegation token is currently valid

Flags:
-h, --help help for delegate

Use "faramesh delegate [command] --help" for more information about a command.) and docs/usage examples, only after #1 and #2 merged.\n\nMust haves for all PRs:\n- Alignment with PRODUCT_CONSTITUTION.md: no mechanism-first UX leakage, evidence-first audit trail.\n- Clear migration path and compatibility notes.\n- Reviewer checklist: security review, legal check for token format, and product-signoff.\n\nRequest: please assign core maintainers and tag with and .

[thebharathkumar]

Thanks for the detailed RFC. The critique is fair — I conflated "matches the existing CLI's expectations" with "matches the project's security posture," and the metrics mux + in-memory choice was the wrong call.

The split is now up — three stacked PRs against main:

• Delegate core store #30 delegate-core-store — core model, opaque HMAC tokens, in-memory + SQLite stores, persistence test, docs. No daemon route changes.
• Delegate transport #31 delegate-transport — case "delegate" on the SDK socket dispatch behind authorizeControlAdmin. Daemon opens ${data_dir}/delegations.db on start. No metrics-mux routes.
• Delegate cli #32 delegate-cli — CLI rewritten to use the new socket transport with --admin-token flag and env-var fallback (FARAMESH_STANDING_ADMIN_TOKEN, FARAMESH_POLICY_ADMIN_TOKEN).

Decisions I made on the questions I had, happy to change either:

• On-disk path: ${data_dir}/delegations.db (sibling to faramesh.hmac.key and the daily-cost store).
• Transport: SDK socket dispatch ({"type":"delegate","op":...,"admin_token":...}), matching compensate and credential. Skipped the MCP gateway for first cut.
• Auth scope: authorizeControlAdmin on every op including reads — exposing who has authority over whom is itself sensitive.
• Signing key: derived from the existing DPR HMAC key with a fixed domain separator (HMAC(dprKey, "faramesh.delegate.v1")), so no second persisted secret.

On the must-haves:

• Migration path / compat notes are documented in Delegate core store #30's description and docs/guides/DELEGATION_GRANTS.md (Operational Notes section).
• PRODUCT_CONSTITUTION.md alignment — couldn't find that file in the repo, so I aligned to the principles you cited directly (evidence-first audit trail → SQLite persistence; no mechanism-first UX leakage → Service API stays free of transport concerns). Happy to cross-reference more precisely if you can point me at where it lives.
• Reviewer checklist items are in each PR's description; please assign reviewers as appropriate.