[p3ris0n]

Summary

This PR implements Phase 2: RBAC (Role-Based Access Control) for AgentGuard, introducing granular, time-bounded resource permissions along with full integration across the smart contract, TypeScript SDK, and operator dashboard.

In addition to core RBAC operations (grant_permission, revoke_permission, check_access), this changeset resolves three critical system requirements:

1. Role Hierarchy in Access Checks: check_access now evaluates role inheritance (Admin >= Premium >= Basic), allowing higher-tier permission grants to satisfy lower-tier access requirements on a resource.
2. Storage Lifecycle Cleanup: Added an agent-level permission index in persistent storage (DataKey::AgentPermissions), ensuring deregister_agent completely purges all active permissions and eliminates orphaned entries if an address is re-registered.
3. Ecosystem & Client Parity: Exposed resource permissions in the @agentguard/sdk client and HTTP middleware, and added interactive resource permission management and simulation verification to the console dashboard.

---

Changes

1. Soroban Smart Contract (contracts/agent_guard/)

• Resource Permissions Core:
  • grant_permission(owner, agent_id, resource_id, role, expires_at): Authenticates owner, validates expires_at > ledger_timestamp, records grant in persistent storage, and updates the agent index.
  • revoke_permission(owner, agent_id, resource_id, role): Validates ownership and existing grant, removes entry from persistent storage, and removes key from the agent index.
• Hierarchical Access Verification:
  • check_access(agent_id, resource_id, required_role): Checks agent status (Active) and inspects candidate roles in descending order (Admin → Premium → Basic). Returns true if any unexpired grant satisfies or exceeds required_role.
  • Retains zero-auth simulation characteristics with no TTL extensions, keeping provider verification overhead minimal.
• Deregistration Cleanup:
  • deregister_agent reads all indexed PermissionKeys for the agent, invokes delete_permission on each, and clears DataKey::AgentPermissions(agent_id).
• Audit Trails:
  • Emits ResourceRoleGranted and ResourceRoleRevoked contract events with indexed topics for agent_id and resource_id.

2. TypeScript SDK (sdk/)

• Client Methods (AgentGuardClient):
  • Added checkAccess(agentPublicKey, resourceId, requiredRole): Promise<boolean>.
  • Added requireAccess(agentPublicKey, resourceId, requiredRole): Promise<void>.
  • Added grantPermission(...) and revokePermission(...) transaction builders.
• Errors & Typings:
  • Exported Permission interface and AgentPermissionDeniedError.
• Middleware:
  • Added enforceAgentPermission(...) and requirePermission(guard, resourceId, role) for route-level authorization via x-agent-public-key.

3. Operator Console & Dashboard (dashboard/)

• Resource Permission Management (AgentDetail.tsx):
  • Added a Resource Permissions card displaying active grants, expiration timestamps, and revocation buttons.
  • Added a modal to grant time-bounded permissions to selected resources.
• Verifier UI (Verify.tsx):
  • Added mode selection between Global Role (verify_agent) and Resource Permission (check_access).
  • Dynamically renders simulated HTTP gateway headers and verification outputs.
• Demo Registry (demo.ts / session.tsx):
  • Seeded initial demo agents with resource grants (e.g. Treasury Agent holds settlement_api).
  • Added local simulated evaluation of checkAccess, grantPermission, and revokePermission.

---

Test & Verification Results

Target	Command	Result
Contract Unit & Integration Tests	cargo test	69 passed, 0 failed
Contract Linter	cargo clippy --workspace --all-targets -- -D warnings	0 warnings
Code Formatting	cargo fmt --all -- --check	Passed
TypeScript SDK Build	npm run build (in sdk/)	Passed (clean tsc)
Dashboard Build	npm run build (in dashboard/)	Passed (clean Vite bundle)

Key Test Scenarios Covered

• Unexpired Admin permission satisfies Premium and Basic access checks on the target resource.
• Unexpired Premium permission satisfies Basic, but rejects Admin.
• Expired permissions return false upon reaching or exceeding ledger timestamp.
• Suspended and Revoked agents fail check_access regardless of permission validity.
• Calling deregister_agent permanently deletes all permission entries from storage; subsequent re-registration of the same address has zero leftover access.