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
}
```