@claude Add machine/service-account (agent) identities + client-credentials to the family auth model (Authentik + Permit)

[izzywdev]

Originator: FuzeKeys MCP Secrets-Broker.

Context / why: FuzeKeys' identity-vault MCP broker needs LLM agents to authenticate as machine identities acting on behalf of a user, under policy. FuzeFront's model (services/oidc.ts, utils/permit/*) only knows human users synced from Authentik — no service-account/client-credentials path, no "agent acts_on_behalf_of user" concept.

Asks:

1. Bless Authentik service accounts + OAuth2 client-credentials as the family-standard machine-identity primitive; document registration + rotation.
2. Provide guidance/helpers to sync a machine identity into Permit as a distinct principal (not a human user).
3. Define the Agent —delegate_of→ User ReBAC relationship in the shared Permit environment (resource types + relationship) so an agent's reach derives from the user it represents.

Acceptance criteria:

• Documented way to register an agent service account in Authentik + obtain a client-credentials token.
• A Permit delegate_of relationship/role model in the shared env, with a worked permit.check(agent, action, resource) that denies cross-user/cross-tenant.
• No bespoke bearer-token scheme required of consumers.

Notifications requested: @-mention me on contract-freeze of the agent-identity model and on deployment.

STATE: blocks FuzeKeys broker agent-auth (interim: a hashed-token fallback). Cross-links the federated-AuthN issue.

[claude]

Claude finished @izzywdev's task in 10m 58s —— View job • claude/issue-113-20260630-0708 • Create PR ➔

---

Machine/service-account (agent) identities — contract-freeze candidate ✅

Delivered the Permit-side model + delegation logic + tests + the frozen contract. Because master is deploy-on-push and you asked to be notified on contract-freeze before deployment, the deploy-sensitive runtime wiring is scoped as the post-freeze phase — this is a PR, not a merge.

• Read auth/permit model + existing plans (api-tokens, permit-pdp-policy-iac)
• Consult fuzefront-expert (separate agent middleware; app-layer delegate resolution over fragile native tenant-role derivation; gotchas)
• Frozen contract doc: docs/superpowers/plans/2026-06-30-agent-identities.md
• Permit schema IaC: action-less Agent/User resource types + delegate_of relation + idempotent relation sync
• Tested delegation helpers (utils/permit/agent-identity.ts) — worked check that denies cross-user/cross-tenant
• Tests added (schema/relation idempotency + denial coverage); AUTHENTICATION_SETUP.md updated
• Pushed branch

How the acceptance criteria are met

• No bespoke bearer scheme — agents are Authentik service accounts using the standard OAuth2 client-credentials grant; FuzeFront validates the access token against the issuer JWKS. Registration + rotation runbook is in the contract doc (§1).
• Permit delegate_of model + worked check that denies cross-user/cross-tenant — Agent —delegate_of→ User is declared in the schema (backend/src/permit/schema.ts) and recorded for audit; enforcement (checkDelegatedPermission) resolves the agent to its single bound (user, tenant) and runs permit.check as the user:
  • cross-tenant → denied before Permit is consulted (bound tenant pinned; request-supplied tenant ignored);
  • cross-user → impossible (the agent has no grants of its own; only ever resolves to its one bound user).
  • This is safer/more honest than native Permit tenant-role derivation, which isn't clean in the permitio 2.4.0 SDK (per expert review).

Design note

The agent is a distinct Permit principal (agent:<sub>, type:'agent'), never a human user. The recorded relation is for audit/visibility; the binding (delegatesUser, tenant) is the authorization source of truth.

⚠️ Scoped out of this PR (post-freeze, deploy-window only)

Per CLAUDE.md (never bot-merge; contract-freeze → deployment two-gate): the Authentik client-credentials provider, the JWKS verification middleware (authenticateAgentToken + dispatcher), and the agent-binding migration are detailed as tasks in the contract doc (§4) but not implemented here — they touch the deploy-sensitive path and a dependency decision (jose vs openid-client keystore). Applying the schema to the shared Permit env runs through the existing permit:schema sync in a deploy window.

⚠️ Tests not executed in this environment

This action's sandbox blocks npm/node, so I could not run type-check/jest here — the code is verified by inspection and is structured for the existing inject-a-fake unit pattern (no PERMIT_API_KEY needed). Please let CI run cd backend && npm run type-check && npx jest --testPathPattern='permit-schema|permit-agent-schema|agent-delegation'.

@izzywdev — this is the contract-freeze candidate for the agent-identity model. On your freeze sign-off I (or the implementer stream) can pick up §4; you'll be @-mentioned again on deployment.

· branch claude/issue-113-20260630-0708