@claude Define per-resource scopes + sensitivity tiers + time-boxed approval-grant roles in the shared Permit.io model

[izzywdev]

Originator: FuzeKeys MCP Secrets-Broker.

Context / why: The broker needs per-identity/per-secret scopes and auto-release (LOW/MED) vs human-approval (HIGH) tiers. FuzeFront's Permit usage (utils/permit/permission-check.ts, role-assignment.ts, resource-instances.ts) covers org/app checks but the family has no agreed pattern for instance-scoped agent roles, a sensitivity attribute, or a temporary TTL-bounded "approved_release" role.

Asks:

1. Standardize a resource-instance-scoped role pattern for agents (out-of-scope = no assignment = deny).
2. Standardize a sensitivity attribute (LOW/MEDIUM/HIGH) + policy: LOW/MED allow in-scope; HIGH requires a separate read_sensitive action not granted by default.
3. Standardize a time-boxed approved_release role the broker assigns after human approval to satisfy read_sensitive (documented TTL/revocation). Approval queue + notifier stay in the broker; only the decision lives in Permit.

Acceptance criteria:

• Documented Permit conventions for instance scoping, sensitivity tiers, and TTL approval-grants in the shared env.
• Worked example: check(agent,"read_sensitive",card) denies until an approval-grant role is assigned, then allows for the TTL, then denies.

Notifications requested: @-mention me on contract-freeze of these Permit conventions and on deployment.

STATE: depends on the agent-identity issue. Maps the broker design §7 tiers onto Permit; interim broker logic replaced once frozen.

[claude]

Claude finished @izzywdev's task in 7m 29s —— View job • claude/issue-114-20260630-0708 • Create PR ➔

---

@claude — Permit.io model: per-resource scopes + sensitivity tiers + TTL approval-grants

• Read existing Permit usage (permission-check.ts, role-assignment.ts, resource-instances.ts, permit/schema.ts)
• Extend schema IaC to support resource attributes + instance-scoped resource roles
• Add worked Secret resource: sensitivity attr, read/read_sensitive actions, agent_reader + time-boxed approved_release roles
• Add helper module (agent-scopes.ts): instance-scoped assign, TTL grant/revoke, sensitivity→action check
• Write conventions doc + worked example (deny → grant → allow for TTL → deny)
• Add tests (schema + worked-example lifecycle)
• Commit + push
• ⚠️ Build/test could not be run in this env (dependency install is blocked) — see note below

@izzywdev — I've drafted the shared Permit conventions as a proposed contract (not merged — per the repo's deploy-on-push hardening I won't bot-merge; this needs a contract-freeze decision + a deploy window). All three asks are covered, with a runnable worked example.

What's in the PR

1. Per-resource (instance-scoped) agent roles — backend/src/permit/schema.ts

• Extended the resource model (PermitResourceDef) with optional ABAC attributes and instance-scoped roles (PermitResourceRoleDef), and taught syncPermitSchema to propagate them idempotently on create/update.
• Agents get a role against one instance (resource_instance: "<Type>:<key>"). Out-of-scope = no assignment = deny (the backend already fails closed on PDP errors).

2. sensitivity attribute (LOW/MEDIUM/HIGH) + policy — worked-example Secret resource

Sensitivity	Action checked	Granted by
LOW / MEDIUM	read	agent_reader (in-scope) — auto-release
HIGH	read_sensitive	approved_release only — human approval

read_sensitive is a separate action agent_reader does NOT grant. The broker maps tier→action via actionForSensitivity().

3. Time-boxed approved_release role — backend/src/utils/permit/agent-scopes.ts

• grantApprovedRelease(ref, ttlSeconds) → returns { grantedAt, expiresAt, ttlSeconds }; refuses non-positive TTL (no permanent grants).
• TTL is broker-enforced: the broker persists expiresAt and schedules revokeApprovedRelease (Permit holds no timer). Queue + notifier stay in the broker; only the decision (assignment) lives in Permit.

Helpers (assignAgentScope, revokeAgentScope, grantApprovedRelease, revokeApprovedRelease, checkAgentRead) take an injectable client so the lifecycle is testable without a live PDP.

Acceptance criteria

• ✅ Documented conventions — docs/guides/PERMIT_AGENT_SCOPES.md (instance scoping, sensitivity tiers, TTL approval-grants, + "adopt this pattern" guide).
• ✅ Worked example — backend/tests/agent-scopes.test.ts exercises check(agent,"read_sensitive",card): deny → grant → allow (within TTL) → deny (after revocation), with a fake PDP that resolves permissions straight from the schema.

⚠️ Note: build/tests not executed here

Dependency installation (npm install) is blocked in this CI sandbox and no TypeScript/Jest toolchain is present, so I could not run type-check/build/test. Changes were reviewed manually for type correctness. Please run before freezing:

cd backend && npm install && npm run type-check && npm test -- --testPathPattern='permit-schema|agent-scopes'

Dependencies / notes

• Depends on the agent-identity issue: these conventions assume agent:… principals already exist as Permit users. Identity minting is out of scope here.
• Adding Secret to the shared schema means the next deploy's idempotent schema-sync creates it in the shared Permit env — additive, gated on permit.enabled.

· branch claude/issue-114-20260630-0708