feat(agent-harness): authorize durable grants and registered clients

[iscekic]

Summary

No new behavior — this change prepares access checks for later product changes.

---

Maintainer changelog

New RequestScopeSchema, HarnessCapabilityScopeSchema, HarnessCapabilityScope, and ClaimsSchema contracts validate requests and bind internal capabilities to current conversation authority and server-held grants.
Capabilities bind the audience, conversation, operation, definition version, input digest, dispatch, and target for at most 60 seconds.
Observed authority loss permanently revokes grants; backend authorization survives origin-client sign-out, while local authorization requires the registered client and its current session.

Files

• apps/web/src/lib/agent-harness/authorization.ts — Added (+220 lines). Adds request authorization, explicit grant creation, and capability minting and verification helpers. Reloads ownership, generation, account status, retirement, and organization access from primary storage, including inherited roles. Rebuilds TRPCContext from the current user and trusted audit fields, without caller-supplied actors, headers, IP addresses, or admin flags. Transactional request and grant checks require the current client session and reject a mismatched organization scope. Stores expiring grant references bound to the conversation, owner, client, and generation instead of client bearer tokens. Capability renewal cannot create or revive grants; storage errors remain retryable without permanent revocation. harnessInputDigest hashes validated canonical JSON with SHA-256. Capability signing uses HS256, the existing NEXTAUTH_SECRET, and issuer agent-harness; expiry cannot exceed the grant expiry. Verification checks strict claims, audience, timestamps, the full expected scope, current authority, and known tool executor/version contracts. Client dispatch additionally requires the grant's client and its advertised tool version; backend dispatch ignores origin-client connectivity, logout, and session revocation.

The registerClient and revokeClient commands persist account-bound ClientSchema registrations with authenticated browser or device sessions and advertised tool versions.
Shared locks and conditional upserts order registration against revocation; replays cannot transfer ownership, rebind sessions, or revive clients.
The new authenticateHarnessIdentity and requireHarnessClient helpers reject bots, internal credentials, unsupported bearer authentication, blocked accounts, stale sessions, and revoked clients.

Files

• apps/web/src/lib/agent-harness/clients.ts — Added (+147 lines). Derives browser or mobile identity from request authentication, never command input. Rejects authorization headers without a device session and checks the registration kind. Hashes the account identifier and current web or device token pepper; device bindings also include the device-session identifier. Locks and reloads the client, account, and unrevoked account-owned device session. Validates CommandSchema and accepts only registration or revocation commands inside a transaction. Registration replay updates only tool availability for the same owner, kind, and session. Revocation inserts a permanent tombstone even before registration and preserves the first revocation time. Normalizes identifier casing and returns ClientSchema with normalized revokedAt, without exposing the session binding. Denied access returns FORBIDDEN.

Tests: 1 file added, apps/web/src/lib/agent-harness/authorization.test.ts (+692 lines), for authorization, grants, capabilities, and client registration coverage, including PostgreSQL race cases.
Generated: 0 files changed.

---

Verification

No manual tests ran because this level adds helpers; later levels compose the routes and runtime.

Visual Changes

Visual Changes: N/A

Reviewer Notes

• Scope: Level 8 against level 7 only. This level adds helpers, not live routes, composed runtime authorization, or native protection.
• Automated checks: The handoff reports six scoped commands and 23 pure tests passed. The six PostgreSQL cases did not run locally.

Human steps

• before merge: Run the six PostgreSQL cases in continuous integration (CI).
• before merge: Complete backend, browser, iOS, and Android verification on the completed stack tip.
• before merge: Merge the stack from the lowest level upward after the section passes its completion gate.

This level reuses the existing signing secret and database contracts; it adds no environment value, migration, or separate setup step.

Notes

No manual runtime verification ran for this level. Full backend, browser, iOS, and Android verification remains required on the completed stack tip.

The six PostgreSQL cases remain required in CI. Local pure tests do not prove database race behavior.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662 ← this PR
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718 (tip)

[kilo-code-bot]

WARNING: Unknown operations skip executor/version checks

currentDispatch only enforces executorKind and definitionVersion when toolDefinitions contains the operation. A missing definition makes this condition false, so mint and verify succeed for arbitrary backend or interaction operations. Deny unknown tools so this helper matches the known-tool contract.

Suggested change

	definition &&
	!definition ||

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
apps/web/src/lib/agent-harness/authorization.ts	157	Unknown operations skip executor/version checks

Files Reviewed (3 files)

• apps/web/src/lib/agent-harness/authorization.ts - 1 issue
• apps/web/src/lib/agent-harness/clients.ts - 0 issues
• apps/web/src/lib/agent-harness/authorization.test.ts - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 285.8K · Output: 30K · Cached: 726.4K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s7}