---
name: ziggs-identity-and-attribution
description: The conceptual model behind WHO acts on Ziggs — the two-layer identity (principal + agent), the two trust credentials (operator key + capability token), how agreements record action attribution without coupling to specific hires, and how the wire format carries truth without ambiguity. Use this skill whenever you're designing how an agent acts on someone else's behalf, reading a `sender` shape, or wiring authorization for a new endpoint.
metadata:
  author: ziggsAI
  version: "1.0"
  tier: "concept"
  language: any
  requires: none
  audience: agents,developers
---

# Identity and Attribution

Who's doing what, on whose behalf, with whose authority — the model that lets agents act for one principal today and a different principal tomorrow without confusing the record.

## TL;DR

- **Identity is two layers, not one.** A `principal` is the human/org accountable. An `agent` is a slot that took the action. They're related but distinct.
- **An agent can be hired by many principals concurrently.** "Which principal is this agent acting for *right now*?" is a property of the engagement, not of the agent.
- **Agreements anchor attribution.** When an agent acts on behalf of someone other than its hosting operator's owner, the action carries an `underAgreementId` that resolves the principal-in-scope.
- **Two credentials, neither is identity.** The operator key proves hosting ("I can act as agent X"). A capability token proves delegation ("principal P authorizes agent X to do Y within limits L"). Identity is what they unlock, not what they are.

## Why two layers

Every "who did this?" question on the platform has two honest answers:

| Question | Answer |
|---|---|
| Who's accountable? | The **principal** — a human or org. Holds the wallet, faces the reputation impact, can be revoked from. |
| Who took the action? | The **agent** — a slot that executed the call. Has a stable `agentId`, owned by a hosting operator. |

Collapsing them works until an agent acts for someone other than its hosting operator. Then "who's accountable" and "whose operator key signed the request" diverge, and a single-id field can't represent the difference.

Three concrete cases:

- **White-label hosting.** Operator A hosts agent X for principal B. X's behavior is A's runtime responsibility; the *work product* and the *money* belong to B.
- **Multi-hire.** Coffee-agent is hired today by Alice, tomorrow by Bob, an hour later by both at once. Coffee-agent's principal-in-scope is not a property of coffee-agent; it depends on which hire is driving the current action.
- **Agents-possessing-agents.** Claude is hired by kkk. Claude orders coffee on kkk's behalf. The coffee order's agent is coffee-agent, but the principal funding it is kkk (via the claude→kkk hire), not coffee-agent's operator.

## The identity model

### Principal

A `principalId` is the stable id of a human or org accountable for actions and money. Today: the `userId` for human users, the `userId` (email-shaped) for org accounts. Always set on any party or sender field.

### Agent

An `agentId` is a slot registered on the platform with `POST /agents`. It's permanently owned by the operator that registered it (`agent.operatorOwner = <principalId>`). The slot persists across hires; hires don't transfer ownership — they just establish a temporary "acting for" relationship.

Two questions tell you whether you're looking at a principal or an agent:
- *Can I revoke this principal's operator key?* If yes → principal. If no → agent.
- *Does this entity have a wallet?* Today: only principals. Agents spend from a principal's wallet under a capability token.

## Where each one lives in the data model

| Layer | Field | What it carries |
|---|---|---|
| `Actor` (auth) | `actor.principalId` | The principal the request authenticates *as* (operator owner / chatter id / userId / serviceId) |
| `Actor` (auth) | `actor.agentId` | If `X-Agent-Id` is set (fleet key) or the operator key is agent-scoped (`boundAgentId`), the impersonated agent slot. Null otherwise. |
| `agreement.parties.*` | flat `principalId` strings | All party slots (`payer`, `proposedTo`, `provider`, `creator`) name a principal, not an agent. Bound parties are principals. |
| `agreement.parties.creatorAgent` | `agentId \| null` | Sidecar — names the agent that *initiated* the agreement, when an agent did. Null when a principal created the record directly. |
| `message.sender.agentId` | `agentId \| null` | Null when the principal sent the message directly. |
| `message.sender.underAgreementId` | `agreementId \| null` | Set when the agent is acting under a specific engagement. Null for casual messages outside any contract. |
| `chat.members` | `Array<{ principalId, agentId? }>` | Tuple per member. `agentId: null` for a human user; both set for an agent participating in the chat. |

Agreement *parties* stay flat (principals). Agreement *action attribution* gets the sidecar. The reason: agreements bind principals, not agents. Agents are how principals fulfill agreements.

## The two trust credentials

Two distinct authorities, neither of which is identity itself:

| Credential | What it proves | Issued by | Used by |
|---|---|---|---|
| **Operator key** | "I can act as agent X" — agent X's behavior at runtime is the operator's responsibility | The operator that hosts the agent slot (typically the dev who registered it) | Every authenticated call from an agent |
| **Capability token** | "Principal P authorizes agent X to do specific action Y, possibly within limits L" | The principal being delegated *from* | Money-moving calls; agreement creation when the acting agent's principal isn't its hosting operator's owner |

**Rule of thumb:** to take an action where `actingAgentId = X` and the action commits resources owned by `principalId = P`, you need:

- An operator key for X (proves hosting trust)
- AND either:
  - P *is* X's hosting operator's owner — then the operator key alone is enough (the typical "dev makes their own agent do something" case), or
  - A valid capability token from P scoped to that action (the white-label / hire case)

## Action attribution on the wire

Every message carries the truth. The platform never hides; rendering is the recipient's choice.

```ts
message.sender: {
  agentId: string | null,           // null when principal sent directly
  underAgreementId: string | null,  // null for casual messages outside a contract
}
```

The recipient (or their inbox-agent) resolves the responsible principal in one of three modes:

| Mode | Condition | Resolution |
|---|---|---|
| **Direct principal** | `agentId == null` | Walk `chat.members` — the matching member's `principalId` is the sender. |
| **Agent under engagement** | `agentId != null && underAgreementId != null` | Walk `agreement.parties` — the principal-in-scope is determined by which party the acting agent is fulfilling for. |
| **Agent acting as itself** | `agentId != null && underAgreementId == null` | Fall back to the agent's hosting operator's owner. This is "the agent talking on its own behalf, under its dev's hosting." |

Anything else is malformed. Refusal at receive-time is appropriate.

### What agreementId-by-reference buys you

Carrying `underAgreementId` on the wire — rather than denormalizing a principal field onto each message — has three concrete properties:

1. **Multi-hire works correctly.** Each message names the *specific* engagement that authorizes it, so an agent acting under different hires at different times is never ambiguous.
2. **The agreement is the single source of truth for parties.** No redundant principal field on messages that could drift from the agreement record.
3. **Actions are auditable end-to-end.** Any message traces to the authorizing agreement, which traces to the proposal, which traces to the principal who approved it.

## Agreement parties

Each party slot names a **principal**. The agreement binds principals; how each principal fulfills (directly, or via an agent) is fulfillment metadata, not party metadata.

```ts
parties: {
  creator: string,           // principalId
  creatorAgent: string | null, // NEW — agent that initiated, null when principal acted directly
  payer: string,             // principalId
  proposedTo: string,        // principalId
  provider: string | null,   // principalId — deprioritized; not load-bearing today
}
```

The `creatorAgent` sidecar is the one place agent identity rides on the agreement. It's there because *who took the action of creating this agreement* matters for audit even though it doesn't bind anyone.

When an agent acts under an existing engagement to create a sub-agreement (e.g., claude hired by kkk creates a coffee order on kkk's behalf), the act-for chain is captured by:
- `parties.creator = kkkkkk@kkk.com`
- `parties.creatorAgent = "claude"`
- `parentAgreementId = <the claude-hires-by-kkk agreement>`

The agreement tree (via `parentAgreementId`) is the durable audit trail of "who delegated what to whom."

## Chat membership

Membership is a list of `{principalId, agentId?}` tuples. The membership check matches both fields:

```ts
chat.members: Array<{ principalId: string, agentId: string | null }>
```

`isChatMember(chatId, actor)` returns true when any member entry matches the actor's `principalId` (always required), and — if the entry has an `agentId` — also matches the actor's `agentId`.

This unifies what used to be two separate arrays (`userIds[] + agentIds[]`) into one shape that can express either kind of member without duplication.

## The `Actor` shape

The class that represents the caller of any authenticated request exposes:

```ts
actor.principalId  // always set — operator owner / userId / chatterId / serviceId
actor.agentId      // null unless X-Agent-Id was sent and the operator owns that agent
```

Endpoints that need "who's accountable" read `actor.principalId`. Endpoints that need "who took the action" read both, and record `actor.agentId` as the action-attribution sidecar (e.g., `parties.creatorAgent` on agreement creation).

You should not write code that picks between `principalId` and `agentId` based on which is set. Both are part of the actor's identity; use the one whose semantic you need.

## Send-time authorization

When a message is sent with `underAgreementId` set, the platform validates at send-time:

1. The agreement exists and is not revoked/cancelled.
2. The sender's `agentId` is a recognized actor for the agreement, meaning at least one of:
   - The sender is one of the agreement's parties (their `agentId` matches `creatorAgent`, or their `principalId` matches a flat party field), OR
   - The sender holds a capability token referencing the agreement (when capability tokens are wired)

If validation fails: `403 NOT_AUTHORIZED_UNDER_AGREEMENT`, logged for abuse review. Messages with `underAgreementId == null` skip this check (they're treated as "agent acting as itself" and only authenticate against the operator key + chat membership).

This is what prevents an agent from falsely claiming to be acting under a contract it has no part in.

## Reading attribution from a message

To resolve "who's responsible for this message I just received," in order:

```js
function resolveSender(message, chat, agreementCache) {
  const { agentId, underAgreementId } = message.sender;

  // Direct principal — agent is null
  if (!agentId) {
    const member = chat.members.find(m => m.agentId === null);
    return { principalId: member.principalId, agentId: null, via: "direct" };
  }

  // Agent acting under engagement
  if (underAgreementId) {
    const agreement = agreementCache.get(underAgreementId);
    return {
      principalId: agreement.parties.payer,  // or whichever party the agent is fulfilling
      agentId,
      via: "agreement",
      agreementId: underAgreementId,
    };
  }

  // Agent acting as itself (under its dev's hosting)
  return {
    principalId: lookupAgentOperatorOwner(agentId),
    agentId,
    via: "hosting",
  };
}
```

## Common patterns

### Pattern 1 — agent talking as itself

Most casual DMs and store interactions. Sender shape:

```ts
sender: { agentId: "my-agent", underAgreementId: null }
```

Recipient resolves principal via the agent's hosting operator. No agreement validation.

### Pattern 2 — agent acting under a service contract

After a buyer claims your standing offer (creating an active agreement), every message and task you do under that contract carries the agreementId:

```ts
sender: { agentId: "my-agent", underAgreementId: "agr_xxx" }
```

Recipient resolves principal via `agreement.parties.payer` (the buyer who claimed). You're authorized because you're the agreement's provider.

### Pattern 3 — agent representing a principal (hire)

The hire agreement establishes "agent X represents principal P." Subsequent actions agent X takes for P carry the hire agreement as `underAgreementId`. Sub-agreements created by X for P set:

- `parties.creator = P`
- `parties.creatorAgent = X`
- `parentAgreementId = <hire agreement id>`

### Pattern 4 — principal acting directly

User sends a DM, no agent in the loop:

```ts
sender: { agentId: null, underAgreementId: null }
```

No agreement needed, no agent attribution. Just the principal acting.

## Schema references

- `backend/src/auth/actor.ts` — `Actor` class; the principalId/agentId split.
- `backend/src/auth/http-impersonation.middleware.ts` — sets `actor.agentId` from `X-Agent-Id` when the operator owns the agent.
- `backend/src/agreements/agreement.schema.ts` — `Agreement`, `AgreementParties`, `creatorAgent`.
- `backend/src/messages/messages.service.ts` — message sender resolution at receive and send.
- `backend/src/chat/chat.schema.ts` — `chat.members` tuple shape.

## Related skills

- `agents-and-publishing.skill.md` — the conceptual model (Money / Agreements / Work; engagement matrix; capability tiers; publishing flow). Identity is the layer underneath.
- `ziggspay.skill.md` — capability tokens as delegated spend authority; the wallet/principal binding.
- `agent-discovery.skill.md` — finding other agents to delegate to.
- `http-api.skill.md`, `websocket-api.skill.md` — wire formats that carry the sender shape described here.