sentryagent-idp/docs/engineering/06-walkthroughs.md

# 06 — Code Walkthroughs

Last verified against commit: `1f95cfe89d1f45fa43b9fb7cff237f07bf9e889e`

These walkthroughs trace three real production code paths from the HTTP request
to the database and back. Every step includes a `file:line` reference and a
"why" annotation explaining the design decision.

---

## Walkthrough 1 — Token Issuance

**Request:** `POST /api/v1/token` with `grant_type=client_credentials`

This is the most security-critical path in the codebase. An AI agent calling this
endpoint is proving its identity and receiving a token that grants access to the
entire API for one hour.

---

### Step 1 — Express middleware stack

**File:** `src/app.ts` lines 57–83

```
helmet()          → security headers
cors()            → CORS headers
morgan()          → access log line (skipped in test env)
express.json()    → parse JSON bodies
express.urlencoded({ extended: false }) → parse form-encoded bodies
metricsMiddleware → start request timer, record counters on finish
```

**Why `extended: false`?** The token endpoint receives `application/x-www-form-urlencoded`
bodies (RFC 6749 mandates this format for OAuth 2.0). The `express.urlencoded`
middleware parses them into `req.body`. `extended: false` uses the native `querystring`
parser, which is sufficient and avoids `qs` library complexity for flat key-value data.

---

### Step 2 — Route dispatch

**File:** `src/routes/token.ts` line 24

```typescript
router.post('/', asyncHandler(rateLimitMiddleware), asyncHandler(tokenController.issueToken.bind(tokenController)));
```

**Why no `authMiddleware` here?** The token endpoint is where the agent _gets_ its
token — it cannot present a Bearer token to authenticate. Instead, credentials go
in the request body (`client_id`, `client_secret`). `POST /token` is deliberately
unauthenticated at the transport layer; authentication happens inside the controller.

**Why `asyncHandler`?** Express does not natively support async middleware. `asyncHandler`
wraps the async function and calls `next(err)` if the promise rejects, routing the
error to `errorHandler`.

---

### Step 3 — Rate limit check

**File:** `src/middleware/rateLimit.ts`

The rate limiter checks a Redis sliding-window counter for the client's IP address.
If the counter exceeds 100 requests/minute, it throws `RateLimitError` (429).

**Why Redis, not in-memory?** If the server restarts or scales horizontally to multiple
instances, an in-memory counter would reset. Redis maintains the counter across
instances and restarts.

---

### Step 4 — Controller: validate grant_type

**File:** `src/controllers/TokenController.ts` lines 84–103

```typescript
issueToken = async (req: Request, res: Response, _next: NextFunction): Promise<void> => {
  const body = req.body as ITokenRequest;

  if (!body.grant_type) { ... return res.status(400).json({error: 'invalid_request', ...}) }
  if (body.grant_type !== 'client_credentials') { ... return res.status(400).json(...) }
```

**Why does this method catch errors itself instead of calling `next(err)`?** The token
endpoint must return errors in the **OAuth 2.0 error format** (`{ error, error_description }`)
per RFC 6749 §5.2, not the standard SentryAgent.ai format (`{ code, message }`). The
`mapToOAuth2Error()` helper translates `AuthenticationError` and `AuthorizationError`
into OAuth2 error codes. The `_next` parameter is intentionally unused for the error path.

---

### Step 5 — Controller: Joi validation and credential extraction

**File:** `src/controllers/TokenController.ts` lines 106–138

```typescript
const { error, value } = tokenRequestSchema.validate(body, { abortEarly: false });
// ...
// Support HTTP Basic auth fallback (RFC 6749 §2.3.1)
const authHeader = req.headers['authorization'];
if (authHeader?.startsWith('Basic ')) {
  const base64 = authHeader.slice(6);
  const decoded = Buffer.from(base64, 'base64').toString('utf-8');
  const colonIndex = decoded.indexOf(':');
  clientId = decoded.slice(0, colonIndex);
  clientSecret = decoded.slice(colonIndex + 1);
}
```

**Why `abortEarly: false`?** This returns all validation errors at once, so the
client can fix all problems in one round trip.

**Why Basic auth support?** RFC 6749 §2.3.1 specifies that client credentials MAY
be sent via HTTP Basic authentication. Some OAuth libraries default to this method.

---

### Step 6 — Controller: scope validation

**File:** `src/controllers/TokenController.ts` lines 141–151

```typescript
const requestedScope = tokenBody.scope ?? 'agents:read';
const validScopes = ['agents:read', 'agents:write', 'tokens:read', 'audit:read'];
const scopeList = requestedScope.split(' ');
const invalidScope = scopeList.find((s) => !validScopes.includes(s));
if (invalidScope) { return res.status(400).json({error: 'invalid_scope', ...}) }
```

**Why validate scopes here?** Scope validation at the controller layer provides an
RFC 6749-compliant `invalid_scope` error before we even look up the agent. This is
faster and gives the client a clearer error message.

---

### Step 7 — Service: agent lookup

**File:** `src/services/OAuth2Service.ts` lines 83–94

```typescript
const agent = await this.agentRepository.findById(clientId);
if (!agent) {
  void this.auditService.logEvent(clientId, 'auth.failed', 'failure', ..., { reason: 'agent_not_found', clientId });
  throw new AuthenticationError('Client authentication failed...');
}
```

**Why log auth failures?** Failed authentication attempts may indicate a brute-force
attack or a misconfigured client. Having them in the audit log enables incident
investigation and alerting.

**Why not distinguish between "agent not found" and "wrong secret" in the error message?**
Revealing which is wrong gives an attacker information — they can enumerate valid
`client_id` values by checking whether they get "agent not found" vs "wrong secret".
Both cases return the same message.

---

### Step 8 — Service: credential verification

**File:** `src/services/OAuth2Service.ts` lines 97–131

```typescript
const { credentials } = await this.credentialRepository.findByAgentId(clientId, { status: 'active', page: 1, limit: 100 });

for (const cred of credentials) {
  const credRow = await this.credentialRepository.findById(cred.credentialId);
  if (credRow) {
    if (credRow.expiresAt !== null && credRow.expiresAt < new Date()) { continue; }

    let matches: boolean;
    if (credRow.vaultPath !== null && this.vaultClient !== null) {
      matches = await this.vaultClient.verifySecret(clientId, credRow.credentialId, clientSecret);
    } else {
      matches = await verifySecret(clientSecret, credRow.secretHash);
    }
    if (matches) { credentialVerified = true; break; }
  }
}
```

**Why iterate over multiple credentials?** An agent can have multiple active
credentials (e.g. one per service that calls it). The agent rotates credentials
one at a time — if credential A is rotated while service X is still using it,
service X will fail. By checking all active credentials, we allow overlapping rotation.

**Why check expiry before hashing?** Bcrypt is intentionally slow (~100ms). Checking
expiry first is a cheap early exit that avoids the bcrypt computation on expired
credentials.

---

### Step 9 — Service: status and monthly limit checks

**File:** `src/services/OAuth2Service.ts` lines 144–176

```typescript
if (agent.status === 'suspended') { throw new AuthorizationError(...) }
if (agent.status === 'decommissioned') { throw new AuthorizationError(...) }

const monthlyCount = await this.tokenRepository.getMonthlyCount(clientId);
if (monthlyCount >= FREE_TIER_MAX_MONTHLY_TOKENS) { throw new FreeTierLimitError(...) }
```

**Why check status after credential verification?** We verify credentials first so
a suspended agent with a wrong secret gets `AuthenticationError` (401) not
`AuthorizationError` (403). This prevents leaking which agents are suspended to
unauthenticated callers.

---

### Step 10 — Service: sign the JWT

**File:** `src/services/OAuth2Service.ts` lines 179–190

```typescript
const jti = uuidv4();
const payload: Omit<ITokenPayload, 'iat' | 'exp'> = { sub: clientId, client_id: clientId, scope, jti };
const accessToken = signToken(payload, this.privateKey);
```

**File:** `src/utils/jwt.ts` lines 19–31

```typescript
export function signToken(payload: Omit<ITokenPayload, 'iat' | 'exp'>, privateKey: string): string {
  const now = Math.floor(Date.now() / 1000);
  const fullPayload: ITokenPayload = { ...payload, iat: now, exp: now + TOKEN_EXPIRES_IN };
  return jwt.sign(fullPayload, privateKey, { algorithm: 'RS256' });
}
```

**Why RS256 instead of HS256?** RS256 (RSA asymmetric) allows any consumer of the
token to verify it using the public key without needing the private signing key.
HS256 (HMAC symmetric) would require sharing the secret with every service that
verifies tokens.

**Why `jti` (JWT ID)?** The `jti` is a unique identifier for this specific token.
It is used as the key in the Redis revocation list. Without `jti`, you cannot
revoke a single token without revoking all tokens for the agent.

---

### Step 11 — Service: fire-and-forget operations

**File:** `src/services/OAuth2Service.ts` lines 193–207

```typescript
void this.tokenRepository.incrementMonthlyCount(clientId);
void this.auditService.logEvent(clientId, 'token.issued', 'success', ..., { scope, expiresAt });
tokensIssuedTotal.inc({ scope });
```

**Why `void` (fire-and-forget)?** The token has been signed and is ready to return.
Waiting for the Redis increment and audit write would add ~5–10ms to every token
request. These operations are best-effort — if they fail, the token is still valid.

**Why is the Prometheus `.inc()` call synchronous?** Prometheus counters are
in-process memory operations — they do not write to Redis or PostgreSQL. They are
O(1) and sub-microsecond.

---

### Step 12 — Response

**File:** `src/controllers/TokenController.ts` lines 163–167

```typescript
res.setHeader('Cache-Control', 'no-store');
res.setHeader('Pragma', 'no-cache');
res.status(200).json(tokenResponse);
```

**Why `Cache-Control: no-store`?** RFC 6749 §5.1 mandates that token responses
must not be cached. Without this header, a shared proxy or CDN could cache the
response and replay it to another client.

Final response:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agents:read agents:write"
}
```

---

## Walkthrough 2 — Agent Registration

**Request:** `POST /api/v1/agents` with Bearer token and agent data JSON body

After token issuance, registering an agent is the second most common operation.
This walkthrough shows a request that goes through all three auth middleware layers.

---

### Step 1 — Middleware stack

**File:** `src/app.ts` lines 57–83 (same security and parsing middleware as Walkthrough 1)

---

### Step 2 — Route dispatch

**File:** `src/routes/agents.ts` lines 22–27

```typescript
router.use(asyncHandler(authMiddleware));
router.use(opaMiddleware);
router.use(asyncHandler(rateLimitMiddleware));
router.post('/', asyncHandler(agentController.registerAgent.bind(agentController)));
```

All three middleware run on every request to the agents router before the handler.

---

### Step 3 — Auth middleware: Bearer token verification

**File:** `src/middleware/auth.ts` lines 28–77

```typescript
const authHeader = req.headers['authorization'];
if (!authHeader || !authHeader.startsWith('Bearer ')) { throw new AuthenticationError(...) }

const token = authHeader.slice(7).trim();
const publicKey = process.env['JWT_PUBLIC_KEY'];
let payload: ITokenPayload;
try {
  payload = verifyToken(token, publicKey);
} catch (err) {
  if (err instanceof TokenExpiredError) { throw new AuthenticationError('Token has expired.') }
  if (err instanceof JsonWebTokenError) { throw new AuthenticationError('Token signature is invalid.') }
}

const redis = await getRedisClient();
const revocationKey = `revoked:${payload.jti}`;
const isRevoked = await redis.get(revocationKey);
if (isRevoked !== null) { throw new AuthenticationError('Token has been revoked.') }

req.user = payload;
next();
```

**Why check Redis after signature verification?** Signature verification is a pure
cryptographic operation (no I/O). If the token is expired or has a bad signature,
there is no need to hit Redis. The fast path exits early; Redis is the slower
secondary check.

**Why `await getRedisClient()` instead of storing the client?** `getRedisClient()`
returns the same singleton every time — the connection is created once and reused.
The `await` is fast (no I/O after the first call).

---

### Step 4 — OPA middleware: scope enforcement

**File:** `src/middleware/opa.ts` lines 230–257

```typescript
const input: OpaInput = {
  method: req.method,               // "POST"
  path: req.baseUrl + req.path,     // "/api/v1/agents"
  scopes: req.user.scope.split(' '), // ["agents:read", "agents:write"]
};

if (!evaluate(input)) {
  next(new AuthorizationError());
  return;
}
```

For `POST /api/v1/agents`, the policy requires `["agents:write"]`. If `agents:write`
is not in the token's scope, the request is rejected with 403 before the controller
runs.

**Why reconstruct the full path with `req.baseUrl + req.path`?** The OPA policy
uses full paths (`/api/v1/agents/:id`). Inside a nested router, `req.path` is
relative to the router's mount point (e.g. `/`). `req.baseUrl` is the mount prefix
(`/api/v1/agents`). Concatenating them gives the full path the policy expects.

---

### Step 5 — Controller: validation

**File:** `src/controllers/AgentController.ts` lines 37–60

```typescript
registerAgent = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  if (!req.user) { throw new AuthorizationError() }

  const { error, value } = createAgentSchema.validate(req.body, { abortEarly: false });
  if (error) {
    throw new ValidationError('Request validation failed.', {
      details: error.details.map((d) => ({ field: d.path.join('.'), reason: d.message })),
    });
  }

  const data = value as ICreateAgentRequest;
  const ipAddress = req.ip ?? '0.0.0.0';
  const userAgent = req.headers['user-agent'] ?? 'unknown';

  const agent = await this.agentService.registerAgent(data, ipAddress, userAgent);
  res.status(201).json(agent);
```

**Why check `req.user` in the controller when `authMiddleware` already set it?**
TypeScript's type system marks `req.user` as `ITokenPayload | undefined`. The check
at line 39 narrows the type so subsequent code can use `req.user` without null
assertions. It is a guard, not redundant authentication.

**Why pass `ipAddress` and `userAgent` to the service?** The service logs audit events.
Audit events include the client IP and User-Agent for forensic value. These values
come from the HTTP request, which the service has no access to — so the controller
extracts them and passes them down.

---

### Step 6 — Service: free-tier limit check

**File:** `src/services/AgentService.ts` lines 59–65

```typescript
const currentCount = await this.agentRepository.countActive();
if (currentCount >= FREE_TIER_MAX_AGENTS) {
  throw new FreeTierLimitError('Free tier limit of 100 registered agents has been reached.', ...);
}
```

**Why count before checking email uniqueness?** If the limit is reached, there is
no point checking whether the email already exists. Doing the cheaper check (count)
first avoids an unnecessary query.

---

### Step 7 — Service: email uniqueness check

**File:** `src/services/AgentService.ts` lines 68–71

```typescript
const existing = await this.agentRepository.findByEmail(data.email);
if (existing !== null) { throw new AgentAlreadyExistsError(data.email) }
```

**Why not rely on the database UNIQUE constraint?** We could, but catching a
PostgreSQL `23505` error code in the repository would be less readable and would
not produce a typed `AgentAlreadyExistsError` with a structured `details` field.
The explicit check gives better error messages and keeps the repository layer clean.

---

### Step 8 — Repository: INSERT

**File:** `src/repositories/AgentRepository.ts` lines 67–85

```typescript
async create(data: ICreateAgentRequest): Promise<IAgent> {
  const agentId = uuidv4();
  const result: QueryResult<AgentRow> = await this.pool.query(
    `INSERT INTO agents (agent_id, email, agent_type, version, capabilities, owner, deployment_env, status, created_at, updated_at)
     VALUES ($1, $2, $3, $4, $5, $6, $7, 'active', NOW(), NOW())
     RETURNING *`,
    [agentId, data.email, data.agentType, data.version, data.capabilities, data.owner, data.deploymentEnv],
  );
  return mapRowToAgent(result.rows[0]);
}
```

**Why generate `agentId` in application code instead of relying on `gen_random_uuid()`?**
Because we use the UUID as the OAuth 2.0 `client_id`. We need the UUID before writing
to the database so we can use it in the audit event and the response. Having it in
application code avoids a separate SELECT after the INSERT.

**Why `RETURNING *`?** PostgreSQL's `RETURNING` clause sends back the inserted row
in the same round trip as the INSERT. This avoids a second SELECT to fetch the
newly created record.

---

### Step 9 — Service: audit event

**File:** `src/services/AgentService.ts` lines 76–83

```typescript
await this.auditService.logEvent(
  agent.agentId,
  'agent.created',
  'success',
  ipAddress,
  userAgent,
  { agentType: agent.agentType, owner: agent.owner },
);
```

**Why `await` here but `void` for token audit events?** Agent registration is a
database write operation that happens once. Adding ~5ms for the audit write is
acceptable and ensures the audit event is recorded before the 201 response is sent.
Token issuance happens far more frequently — audit is fire-and-forget there.

---

### Step 10 — Response

**File:** `src/controllers/AgentController.ts` line 56

```typescript
res.status(201).json(agent);
```

Returns the full `IAgent` object with HTTP 201 Created.

---

## Walkthrough 3 — Credential Rotation

**Request:** `POST /api/v1/agents/:agentId/credentials/:credentialId/rotate`

Credential rotation is the process of replacing an existing client secret with a
new one without changing the `credentialId`. This is the recommended security
practice — rotate periodically and rotate immediately after suspected compromise.

---

### Step 1 — Route dispatch

**File:** `src/routes/credentials.ts` line 34

```typescript
router.post('/:credentialId/rotate', asyncHandler(credentialController.rotateCredential.bind(credentialController)));
```

The credentials router is mounted at `/api/v1/agents/:agentId/credentials` in `app.ts`.
The full path becomes `POST /api/v1/agents/:agentId/credentials/:credentialId/rotate`.

---

### Step 2 — Auth middleware

Same as Walkthrough 2, Step 3. Bearer token is verified via RS256 and Redis revocation check.
`req.user` is populated with the JWT payload.

---

### Step 3 — OPA middleware

The path `/api/v1/agents/:agentId/credentials/:credId/rotate` is normalised to
`/api/v1/agents/:id/credentials/:credId/rotate`. The policy requires `["agents:write"]`.

---

### Step 4 — Controller: ownership check

**File:** `src/controllers/CredentialController.ts` lines 127–137

```typescript
rotateCredential = async (req: Request, res: Response, next: NextFunction): Promise<void> => {
  if (!req.user) { throw new AuthenticationError() }

  const { agentId, credentialId } = req.params;

  if (req.user.sub !== agentId) {
    throw new AuthorizationError('You do not have permission to manage credentials for this agent.');
  }
```

**Why check `req.user.sub !== agentId`?** An agent's token contains its own
`agentId` as the `sub` claim. This check enforces that an agent can only manage
its own credentials. Even if an agent has `agents:write` scope, it cannot rotate
another agent's credentials. This is Phase 1 behaviour — there is no admin scope yet.

---

### Step 5 — Controller: request validation

**File:** `src/controllers/CredentialController.ts` lines 139–157

```typescript
const { error, value } = generateCredentialSchema.validate(req.body ?? {}, { abortEarly: false });
// generateCredentialSchema validates optional `expiresAt` field
const data = value as IGenerateCredentialRequest;
const result = await this.credentialService.rotateCredential(agentId, credentialId, data, ipAddress, userAgent);
res.status(200).json(result);
```

**Why `req.body ?? {}`?** The rotation body is optional — an agent may rotate a
credential without an expiry date, in which case the body may be empty. Passing
`undefined` to Joi would cause a different error than passing `{}`.

---

### Step 6 — Service: existence checks

**File:** `src/services/CredentialService.ts` lines 163–177

```typescript
const agent = await this.agentRepository.findById(agentId);
if (!agent) { throw new AgentNotFoundError(agentId) }

const existing = await this.credentialRepository.findById(credentialId);
if (!existing || existing.clientId !== agentId) { throw new CredentialNotFoundError(credentialId) }

if (existing.status === 'revoked') {
  throw new CredentialAlreadyRevokedError(credentialId, existing.revokedAt?.toISOString() ?? ...);
}
```

**Why check `existing.clientId !== agentId`?** Even though OPA restricts the agent
to its own credentials, a malicious actor could craft a request with a valid
`agentId` in the path but a `credentialId` belonging to another agent. This check
ensures that a credential is only accessible to the agent it was created for.

---

### Step 7 — Service: generate new secret and write to Vault or bcrypt

**File:** `src/services/CredentialService.ts` lines 180–192

```typescript
const expiresAt = data.expiresAt !== undefined ? new Date(data.expiresAt) : null;
const plainSecret = generateClientSecret();  // sk_live_<64 hex chars>

let updated: ICredential | null;

if (this.vaultClient !== null) {
  // Phase 2: overwrite the existing Vault secret (KV v2 creates a new version)
  const vaultPath = await this.vaultClient.writeSecret(agentId, credentialId, plainSecret);
  updated = await this.credentialRepository.updateVaultPath(credentialId, vaultPath, expiresAt);
} else {
  // Phase 1: use bcrypt
  const newHash = await hashSecret(plainSecret);
  updated = await this.credentialRepository.updateHash(credentialId, newHash, expiresAt);
}
```

**Why does Vault rotation write to the same path?** Vault KV v2 is versioned — writing
to an existing path creates a new version without overwriting previous versions.
This preserves an audit trail in Vault itself.

**Why does the Vault path stay the same after rotation?** The `vault_path` column
stores the path, not the secret. The path is deterministic:
`{mount}/data/agentidp/agents/{agentId}/credentials/{credentialId}`. Since the
`credentialId` does not change on rotation, the path does not change either.
Only the Vault version at that path changes.

---

### Step 8 — Repository: UPDATE the credential

**File:** `src/repositories/CredentialRepository.ts` lines 180–218

```typescript
// Bcrypt path (updateHash):
UPDATE credentials
SET secret_hash = $1, vault_path = NULL, expires_at = $2, status = 'active', revoked_at = NULL
WHERE credential_id = $3
RETURNING *

// Vault path (updateVaultPath):
UPDATE credentials
SET vault_path = $1, secret_hash = '', expires_at = $2, status = 'active', revoked_at = NULL
WHERE credential_id = $3
RETURNING *
```

**Why `status = 'active'` in the UPDATE?** A credential could theoretically be
in any state when rotated. The UPDATE explicitly sets it to active. This handles
edge cases where a revoked credential is being "un-revoked" by rotation (though
the service layer prevents this — revoked credentials throw `CredentialAlreadyRevokedError`).
The belt-and-suspenders approach at the SQL layer ensures data integrity.

---

### Step 9 — Service: audit event

**File:** `src/services/CredentialService.ts` lines 199–206

```typescript
await this.auditService.logEvent(
  agentId,
  'credential.rotated',
  'success',
  ipAddress,
  userAgent,
  { credentialId },
);
```

The audit event records which credential was rotated. Combined with the timestamp,
this gives a complete rotation history for each credential.

---

### Step 10 — Response

**File:** `src/controllers/CredentialController.ts` line 161

```typescript
res.status(200).json(result);
```

Returns `ICredentialWithSecret` — the updated credential including the new
`clientSecret`. This is the only time the new secret is ever returned. The caller
must store it securely.

```json
{
  "credentialId": "d4e5f6a7-...",
  "clientId": "a1b2c3d4-...",
  "status": "active",
  "clientSecret": "sk_live_4f8a2e9b...",
  "createdAt": "2026-01-15T10:00:00Z",
  "expiresAt": "2027-01-15T10:00:00Z",
  "revokedAt": null
}
```

---

## Walkthrough 4 — A2A Delegation End-to-End

**Request:** `POST /api/v1/oauth2/token/delegate` — one AI agent delegating a scoped capability to another

This walkthrough traces how agent A (an orchestrator) issues a delegation token that grants agent B (a sub-agent) the right to act on its behalf with a restricted scope.

---

### Step 1 — Route dispatch

**File:** `src/routes/delegation.ts`

```typescript
router.post(
  '/token/delegate',
  asyncHandler(authMiddleware),
  opaMiddleware,
  asyncHandler(delegationController.createDelegation.bind(delegationController))
);
```

Both `authMiddleware` and `opaMiddleware` run. The OPA policy requires scope `agents:write` for delegation creation.

---

### Step 2 — Controller: extract delegator and validate

**File:** `src/controllers/DelegationController.ts`

```typescript
const delegatorId = req.user.sub;               // From the Bearer token's sub claim
const { delegatee_id, scope, expires_at } = req.body;
```

The controller validates that `delegatee_id` is a non-empty UUID, `scope` is a non-empty string, and `expires_at` (if provided) is a valid ISO 8601 datetime in the future. It passes these to `DelegationService.createDelegation()`.

---

### Step 3 — Service: verify both agents exist

**File:** `src/services/DelegationService.ts`

```typescript
const delegator = await this.agentRepository.findById(delegatorId);
if (!delegator || delegator.status !== 'active') { throw new AgentNotFoundError(delegatorId) }

const delegatee = await this.agentRepository.findById(delegateeId);
if (!delegatee || delegatee.status !== 'active') { throw new AgentNotFoundError(delegateeId) }
```

Both agents must exist and be in `active` status. A suspended or decommissioned agent cannot participate in delegation.

---

### Step 4 — Service: insert delegation chain record

**File:** `src/services/DelegationService.ts`

```typescript
await this.pool.query(
  `INSERT INTO delegation_chains (chain_id, delegator_id, delegatee_id, scope, status, expires_at)
   VALUES ($1, $2, $3, $4, 'active', $5)`,
  [chainId, delegatorId, delegateeId, scope, expiresAt]
);
```

The `chain_id` is a UUID generated by the service. The `delegation_chains` table provides the authoritative source of truth for which delegations are active, independent of any token.

---

### Step 5 — Response

```json
{
  "chain_id": "f1e2d3c4-...",
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "delegator_id": "a1b2c3d4-...",
  "delegatee_id": "b2c3d4e5-...",
  "scope": "agents:read",
  "status": "active",
  "expires_at": "2026-04-05T00:00:00Z"
}
```

The `token` field is the signed delegation JWT. The delegatee presents this token to `POST /api/v1/oauth2/token/verify-delegation` to prove it has authority to act on the delegator's behalf.

**Why store both the DB record and the JWT?** The DB record allows revocation — when the delegator calls `DELETE /api/v1/delegation-chains/:chainId`, the record is soft-deleted and all subsequent `verify-delegation` calls will fail even if the JWT itself has not yet expired.

---

## Walkthrough 5 — Tier Enforcement Request Lifecycle

**Request:** Any authenticated API request when the organisation's daily call limit is reached

This walkthrough traces how `tierMiddleware` intercepts a request before it reaches the OPA middleware, preventing quota-exceeded traffic from consuming service resources.

---

### Step 1 — Auth middleware passes

Same as Walkthrough 2, Step 3. The Bearer JWT is verified and `req.user` is populated with `sub` (agentId) and `organization_id`.

---

### Step 2 — Tier middleware: fetch org tier

**File:** `src/middleware/tier.ts`

```typescript
const orgId = req.user.organization_id;
const tier = await tierService.fetchTier(orgId);
const config = TIER_CONFIG[tier];
```

`fetchTier()` issues `SELECT tier FROM organizations WHERE organization_id = $1`. Returns `'free'` if no row is found (safe default).

---

### Step 3 — Tier middleware: read daily counter

**File:** `src/middleware/tier.ts`

```typescript
const callsKey = `rate:tier:calls:${orgId}`;
const callsToday = await redis.get(callsKey);
const count = callsToday !== null ? parseInt(callsToday, 10) : 0;

if (count >= config.maxCallsPerDay) {
  throw new TierLimitError('calls', config.maxCallsPerDay, { orgId, tier, current: count });
}
```

The Redis key `rate:tier:calls:<orgId>` is read. If null (first call of the day), count is 0. When count equals or exceeds the tier limit, `TierLimitError` (HTTP 429) is thrown immediately — no further middleware runs.

---

### Step 4 — Tier middleware: increment counter (fire-and-forget)

**File:** `src/middleware/tier.ts`

```typescript
// Set TTL to next UTC midnight if key is new
void redis.multi()
  .incr(callsKey)
  .expireAt(callsKey, nextUtcMidnightUnix())
  .exec();
next();
```

The counter is incremented atomically using a Redis MULTI block. The `EXPIREAT` command sets the key to auto-delete at the next UTC midnight, resetting the daily counter without any scheduled job. The increment is fire-and-forget — the request proceeds immediately to `opaMiddleware`.

**Why expire at UTC midnight rather than a rolling 24-hour window?** Tier limits are documented as "per day", which users interpret as resetting at midnight. A rolling window would allow a user to consume their full daily quota twice within a 48-hour period straddling midnight, which is counterintuitive. UTC midnight is predictable and easy to reason about.

---

### Step 5 — Error handler serialises TierLimitError

**File:** `src/middleware/errorHandler.ts`

```json
HTTP 429
{
  "code": "TIER_LIMIT_EXCEEDED",
  "message": "Daily API call limit reached for your tier.",
  "details": {
    "tier": "free",
    "limit": 1000,
    "current": 1000
  }
}
```

The `Retry-After` header is set to the number of seconds until next UTC midnight so clients can implement automatic backoff.

---

## Walkthrough 6 — Analytics Event Capture Flow

**Trigger:** Any successful token issuance (`POST /api/v1/token`)

This walkthrough traces how an analytics event is captured without affecting the latency of the primary token issuance response.

---

### Step 1 — Token issuance completes

**File:** `src/services/OAuth2Service.ts`

```typescript
const accessToken = signToken(payload, this.privateKey);
// Primary response is ready — analytics is now fire-and-forget
void this.analyticsService.recordEvent(tenantId, 'token_issued');
tokensIssuedTotal.inc({ scope });
```

The `signToken()` call completes synchronously (RSA signing is CPU-bound, not I/O). The controller can now send the response. `analyticsService.recordEvent()` is called with `void` — the `await` is deliberately omitted.

**Why `void` instead of `await`?** Token issuance latency must remain below 100ms (per the QA performance gate). A PostgreSQL write adds 5–15ms. Since analytics data is aggregated (not transactional), losing an occasional event due to an error is acceptable. The response is never delayed for analytics.

---

### Step 2 — AnalyticsService: UPSERT daily counter

**File:** `src/services/AnalyticsService.ts`

```typescript
async recordEvent(tenantId: string, metricType: string): Promise<void> {
  try {
    await this.pool.query(
      `INSERT INTO analytics_events (organization_id, date, metric_type, count)
       VALUES ($1, CURRENT_DATE, $2, 1)
       ON CONFLICT (organization_id, date, metric_type)
       DO UPDATE SET count = analytics_events.count + 1`,
      [tenantId, metricType],
    );
  } catch (err) {
    console.error('[AnalyticsService] recordEvent failed — primary path unaffected', err);
  }
}
```

The `ON CONFLICT DO UPDATE` upsert is atomic. Whether this is the first or the ten-thousandth `token_issued` event for this tenant today, the row is updated correctly. All errors are caught and swallowed — the token has already been returned to the caller.

**Why one row per day per metric, not one row per event?** Storing a row per event would create millions of rows. The daily aggregate model keeps the table compact while still providing daily trend data (the granularity that analytics dashboards need). Sub-day granularity is available from the Prometheus `agentidp_tokens_issued_total` counter if needed.

---

### Step 3 — Dashboard query (deferred)

When a developer visits the analytics page in the developer portal, the portal calls:

```
GET /api/v1/analytics/token-trend?days=30
```

**File:** `src/services/AnalyticsService.ts` — `getTokenTrend(tenantId, 30)`

```sql
SELECT
  gs.date::DATE::TEXT AS date,
  COALESCE(ae.count, 0)::INTEGER AS count
FROM generate_series(
  CURRENT_DATE - 29 * INTERVAL '1 day',
  CURRENT_DATE,
  INTERVAL '1 day'
) AS gs(date)
LEFT JOIN analytics_events ae
  ON ae.date = gs.date::DATE
  AND ae.organization_id = $2
  AND ae.metric_type = 'token_issued'
ORDER BY gs.date ASC
```

The `generate_series` + `LEFT JOIN` pattern ensures all 30 days appear in the result, with `count: 0` for days with no events. This avoids the need for the client to fill in gaps.