feat: agent identity inventory, security hardening, docs rewrite, demo legibility

[GautamTalksDev]

Four bodies of work in one PR. Splitting them at this point would cost more than
the review benefit; noting it honestly rather than pretending otherwise.

Agent identity
Keyring now inventories AI agents as first-class principals: ai_agent kind with
runtime, purpose, tools, owner and declaration status; a declared_agents policy
section; an agent-identity connector. Unregistered agents holding live
credentials are the highest risk state in the system. Keyring inventories itself,
because an access governance tool that exempts itself is not trustworthy. Maps to
OWASP Top 10 for Agentic Applications 2026 (ASI03 Identity and Privilege Abuse,
ASI10 Rogue Agents) and the NIST NCCoE February 2026 concept paper on AI Agent
Identity and Authorization.

Security
Credential redaction across API responses, SSE, MCP results, logs and errors.
Secret scanning over full git history. Loopback binding by default. Removed
application level audit trigger bypasses and the predictable export signing
fallback. Tightened input validation and generic error handling. Added
docs/SECURITY.md.

Documentation
README and all docs rewritten for a public audience, with architecture diagrams,
the TrueForge boundary, safety guarantees and an honest limitations section.

Demo
Status strip with phase and step count, a focus ring that travels with real API
calls, explicit human approval gate. Full automated run 94.8 seconds excluding
the human pause. No synthetic cursor: faking human input would be the exact
failure mode OWASP ASI09 describes.

105 tests passing.

[qodo-code-review]

PR Summary by Qodo

Add agent identity governance and harden public demo surfaces

✨ Enhancement 🐞 Bug fix 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Inventories declared and rogue AI agents as evidence-backed access principals.
• Redacts credentials, preserves audit immutability, and tightens network and input boundaries.
• Rewrites public documentation and clarifies guided demo progress and human approval.

Diagram

sequenceDiagram
  participant S as Identity Sources
  participant C as Agent Connector
  participant K as Keyring Core
  participant A as Keyring API
  participant Q as Approval Queue
  actor O as Operator
  participant L as Audit Ledger
  S->>C: Return agent evidence
  C->>K: Create agent grants
  K->>K: Reconcile and score
  K->>A: Persist approval cards
  A->>Q: Stream redacted results
  Q->>O: Request named decision
  O->>A: Approve hold or reject
  A->>L: Append decision and result

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Split by workstream

• ➕ Smaller review units
• ➕ Simpler rollback and risk isolation
• ➕ Clearer ownership for identity, security, docs, and demo changes
• ➖ Requires coordinating dependent fixture, API, and documentation updates
• ➖ Could leave intermediate branches with inconsistent public behavior

2. Model agents as service accounts

• ➕ Smaller domain-model change
• ➕ Reuses existing reconciliation and policy paths
• ➖ Loses runtime, purpose, reachable-tool, and declaration semantics
• ➖ Can incorrectly merge agent and service-account authority
• ➖ Weakens rogue-agent risk treatment

3. Use an external redaction plugin

• ➕ Potentially broader framework-level coverage
• ➕ Less custom pattern maintenance
• ➖ Still requires domain-aware serialization controls
• ➖ Adds another security-sensitive dependency
• ➖ Does not address stored errors or MCP payloads alone

Recommendation: Keep AI agents as a distinct principal and centralize reusable redaction in core; those are the right architectural choices. If branch history still permits, splitting identity/security from documentation/demo would reduce review risk, but the current implementation should be reviewed as four explicit workstreams with security and audit behavior validated first.

Files changed (89) +3201 / -1952

Enhancement (25) +760 / -112

App.tsxMount guided demo progress strip +7/-0

Mount guided demo progress strip

• Displays persistent phase and step progress whenever guided demo mode is active.

apps/web/src/App.tsx

types.tsExpose AI agent principal metadata to the UI +6/-0

Expose AI agent principal metadata to the UI

• Adds runtime, purpose, tools, registration owner, name, and declaration status to card types.

apps/web/src/api/types.ts

ApprovalCardView.tsxRender agent identity badges and guided focus +24/-1

Render agent identity badges and guided focus

• Distinguishes declared and unregistered agents, shows runtime and reachable tools, and highlights the active demo card.

apps/web/src/components/ApprovalCardView.tsx

ApprovalQueue.tsxAnimate guided focus across approval cards +81/-25

Animate guided focus across approval cards

• Adds a reduced-motion-aware travelling focus ring and delegates summary wording to shared formatting helpers.

apps/web/src/components/ApprovalQueue.tsx

GuidedDemoStatusStrip.tsxAdd guided demo status strip +65/-0

Add guided demo status strip

• Introduces an accessible fixed status bar showing phase labels, human-wait state, and step counts.

apps/web/src/components/GuidedDemoStatusStrip.tsx

useGuidedDemo.tsTrack reconciliation and guided demo steps +41/-8

Track reconciliation and guided demo steps

• Adds explicit reconciliation phase reporting, seven-step progress, and execution-card focus updates.

apps/web/src/hooks/useGuidedDemo.ts

format.tsSummarize agent identities in scan results +23/-0

Summarize agent identities in scan results

• Counts unique human and AI agent identities and formats agent names and system labels.

apps/web/src/lib/format.ts

connector.tsAdd inventory-only agent identity connector +163/-0

Add inventory-only agent identity connector

• Introduces fixture and MCP sources that convert agent registrations and credentials into evidence-backed AI agent grants.

packages/connectors/src/agent-identity/connector.ts

index.tsExport agent identity connector APIs +10/-8

Export agent identity connector APIs

• Publishes agent source, record, options, and connector factories from the package entry point.

packages/connectors/src/index.ts

approval-build.tsBuild safe approval actions for agent grants +23/-2

Build safe approval actions for agent grants

• Supports principal IDs, flags unregistered agents, and keeps agent identity evidence inventory-only.

packages/core/src/approval-build.ts

approval.tsAllow principal IDs in attribution +3/-7

Allow principal IDs in attribution

• Extends resolved attribution targets beyond human person IDs for agent clusters.

packages/core/src/approval.ts

grant.tsAdd AI agent principals and resources +36/-7

Add AI agent principals and resources

• Extends grant systems, principal metadata, resource kinds, and immutable agent field copying.

packages/core/src/grant.ts

identifier.tsAdd stable agent identifiers +1/-0

Add stable agent identifiers

• Introduces agent_id as a first-class identifier kind.

packages/core/src/identifier.ts

index.tsExport agent declaration identity types +3/-8

Export agent declaration identity types

• Publishes the new declaration model while simplifying existing exports.

packages/core/src/identity/index.ts

reconcile.tsReconcile declared AI agents independently +90/-14

Reconcile declared AI agents independently

• Seeds agent clusters, matches exact agent or credential IDs, prevents service-account merging, and emits principal IDs.

packages/core/src/identity/reconcile.ts

run.tsAccept agent declarations in JSON reconciliation +3/-0

Accept agent declarations in JSON reconciliation

• Passes declared agent policy through the standalone reconciliation entry point.

packages/core/src/identity/run.ts

types.tsDefine agent declarations and clusters +18/-2

Define agent declarations and clusters

• Adds AI agent cluster kinds, principal IDs, declaration metadata, and matching signals.

packages/core/src/identity/types.ts

index.tsExport core redaction helpers +1/-0

Export core redaction helpers

• Makes credential and error redaction available to connectors, server, and scripts.

packages/core/src/index.ts

apply.tsNormalize declared agent policy +15/-15

Normalize declared agent policy

• Reads declared_agents safely and exposes them to reconciliation callers.

packages/core/src/policy/apply.ts

index.tsExport declared agent policy APIs +2/-0

Export declared agent policy APIs

• Publishes declared agent types and policy extraction helpers.

packages/core/src/policy/index.ts

types.tsAdd declared agent policy schema +16/-0

Add declared agent policy schema

• Defines required identity, runtime, owner, purpose, credential, and tool fields with empty defaults.

packages/core/src/policy/types.ts

risk.tsMaximize risk for unregistered live agents +9/-1

Maximize risk for unregistered live agents

• Adds a dedicated 45-point rogue-agent reason when undeclared agents hold access.

packages/core/src/risk.ts

scan.tsIntegrate agent identities into scan pipelines +72/-8

Integrate agent identities into scan pipelines

• Loads agent fixtures, applies declarations, preserves agent findings under person filters, and caps demo cards by priority.

packages/server/src/agent/scan.ts

progress.tsAdd identity counts to scan progress +3/-0

Add identity counts to scan progress

• Extends card persistence events with optional human, agent, and system totals.

packages/server/src/api/progress.ts

scan-runner.tsRun agent-aware scans with safe telemetry +45/-6

Run agent-aware scans with safe telemetry

• Loads agent grants, redacts subagent failures, emits identity counts, and prioritizes compact demo queues.

packages/server/src/services/scan-runner.ts

Bug fix (16) +389 / -250

trueforge-caller.tsRedact remote MCP errors +11/-6

Redact remote MCP errors

• Sanitizes HTTP response bodies and MCP error messages before throwing connector errors.

packages/connectors/src/mcp/trueforge-caller.ts

redact.tsAdd shared credential and path redaction +47/-0

Add shared credential and path redaction

• Recursively sanitizes secret-shaped fields and values and removes filesystem paths from errors.

packages/core/src/redact.ts

persist.tsRedact persisted scan failures +3/-7

Redact persisted scan failures

• Sanitizes error text before recording failed scan outcomes.

packages/server/src/agent/persist.ts

routes.tsRedact API outputs and strengthen exports +44/-15

Redact API outputs and strengthen exports

• Sanitizes SSE, cards, errors, audit evidence, and execution results; adds identity counts and unpredictable export signing.

packages/server/src/api/routes.ts

schemas.tsEnforce strict API request schemas +66/-48

Enforce strict API request schemas

• Rejects unknown fields, validates execution streaming queries, and bounds card identifiers.

packages/server/src/api/schemas.ts

app.tsAdd generic sanitized HTTP error handling +31/-9

Add generic sanitized HTTP error handling

• Centralizes safe client errors, generic internal failures, redacted logging, and not-found responses.

packages/server/src/app.ts

store.tsPreserve audit records during demo reset +2/-6

Preserve audit records during demo reset

• Removes application-level trigger disabling and ledger deletion; only card decisions are reset.

packages/server/src/db/store.ts

index.tsBind server to loopback by default +7/-5

Bind server to loopback by default

• Changes the default listener to 127.0.0.1 and sanitizes database startup failures.

packages/server/src/index.ts

http.tsStrictly validate JSON-RPC requests +35/-15

Strictly validate JSON-RPC requests

• Uses Zod to reject malformed envelopes and tool parameters with generic protocol errors.

packages/server/src/mcp/http.ts

tools.tsRedact MCP results and include agent grants +24/-39

Redact MCP results and include agent grants

• Sanitizes text and errors, loads all fixture grants, preserves agent cards, and applies demo queue limits.

packages/server/src/mcp/tools.ts

execute.tsRedact execution details and failures +9/-25

Redact execution details and failures

• Sanitizes connector details, returned errors, caught exceptions, and classified execution failures.

packages/server/src/services/execute.ts

reaudit-cron.tsRedact scheduled re-audit failures +12/-7

Redact scheduled re-audit failures

• Logs sanitized error messages instead of raw exception objects.

packages/server/src/services/reaudit-cron.ts

revoke-runtime.tsFail closed when live write credentials are absent +13/-15

Fail closed when live write credentials are absent

• Removes predictable placeholder tokens and throws when GitHub or Google credentials are not configured.

packages/server/src/services/revoke-runtime.ts

audit-secrets.tsScan complete Git history for secrets +76/-29

Scan complete Git history for secrets

• Uses argument-safe Git execution, scans all refs and reflogs, covers more credential files, and redacts findings.

scripts/audit-secrets.ts

demo-offboard-audit.tsStop bypassing append-only audit controls +5/-23

Stop bypassing append-only audit controls

• Removes trigger disabling and ledger truncation from the demo audit script.

scripts/demo-offboard-audit.ts

register-keyring-agent.tsRedact failed registration responses +4/-1

Redact failed registration responses

• Sanitizes TrueForge response bodies before printing registration failures.

scripts/register-keyring-agent.ts

Tests (14) +355 / -56

format.test.tsTest human and agent summary counts +33/-2

Test human and agent summary counts

• Covers separate identity counts, agent labels, and updated scan headline text.

apps/web/src/lib/format.test.ts

connector.test.tsTest agent identity connector contracts +82/-0

Test agent identity connector contracts

• Verifies evidence-backed grant conversion, self-inventory, and inventory-only mutation refusal.

packages/connectors/src/agent-identity/connector.test.ts

google.contract.test.tsUpdate Google connector contract fixtures +5/-13

Update Google connector contract fixtures

• Aligns expected alternate addresses and formatting with sanitized fixture data.

packages/connectors/src/google.contract.test.ts

revoke.contract.test.tsUpdate revoke fixture aliases +2/-2

Update revoke fixture aliases

• Uses sanitized test-domain addresses in Google revoke and undo-hint assertions.

packages/connectors/src/revoke.contract.test.ts

agent.test.tsTest agent reconciliation and rogue risk +134/-0

Test agent reconciliation and rogue risk

• Covers exact declarations, unregistered-agent isolation, maximum risk, and service-account separation.

packages/core/src/identity/agent.test.ts

reconcile.test.tsSanitize reconciliation test addresses +4/-4

Sanitize reconciliation test addresses

• Updates fixture and adversarial identity tests to use reserved test domains.

packages/core/src/identity/reconcile.test.ts

policy.test.tsTest declared agent policy normalization +22/-1

Test declared agent policy normalization

• Verifies owner and purpose metadata survive policy normalization.

packages/core/src/policy/policy.test.ts

redact.test.tsTest recursive credential redaction +23/-0

Test recursive credential redaction

• Ensures keyed secrets, bearer tokens, access keys, and nested values never survive serialization.

packages/core/src/redact.test.ts

scan.test.tsTest six-system agent-aware fixture scans +7/-6

Test six-system agent-aware fixture scans

• Validates agent inventory, six identity clusters, queue limits, and protected CI attribution.

packages/server/src/agent/scan.test.ts

api.integration.test.tsAssert demo reset preserves audit records +3/-1

Assert demo reset preserves audit records

• Changes integration expectations so reset decisions retain a valid, non-empty append-only ledger.

packages/server/src/api/api.integration.test.ts

app.test.tsTest generic MCP and route errors +24/-0

Test generic MCP and route errors

• Ensures malformed JSON-RPC and unknown routes do not expose stack traces or filesystem paths.

packages/server/src/app.test.ts

audit-append-only.test.tsAlign append-only tests with upgraded database errors +9/-22

Align append-only tests with upgraded database errors

• Updates trigger failure expectations while retaining sequential and concurrent chain verification.

packages/server/src/db/audit-append-only.test.ts

recording.fixture.test.tsSupport agent principal ownership in recordings +3/-1

Support agent principal ownership in recordings

• Resolves recorded cluster ownership from either person or principal IDs.

packages/server/src/recording/recording.fixture.test.ts

recording.integration.test.tsValidate six-system agent recordings +4/-4

Validate six-system agent recordings

• Updates replay limits and event expectations for the agent identity subagent.

packages/server/src/recording/recording.integration.test.ts

Documentation (15) +673 / -637

CONTRIBUTING.mdRewrite contribution and secret-handling guidance +18/-20

Rewrite contribution and secret-handling guidance

• Simplifies setup, required checks, pull request expectations, and rules for credentials and generated data.

CONTRIBUTING.md

README.mdRewrite public product overview and architecture +67/-93

Rewrite public product overview and architecture

• Reframes Keyring for a public audience with agent identity, TrueForge boundaries, safety guarantees, demo instructions, diagrams, and limitations.

README.md

AGENT-IDENTITY.mdDocument the agent identity governance model +115/-0

Document the agent identity governance model

• Explains evidence sources, declarations, rogue-agent risk, self-inventory, limitations, and OWASP/NIST mappings.

docs/AGENT-IDENTITY.md

AGENT.mdClarify Keyring agent configuration and flow +31/-57

Clarify Keyring agent configuration and flow

• Rewrites agent, stub, registration, networking, reconnect, and governance-ledger guidance.

docs/AGENT.md

API.mdRewrite HTTP API and scan-driver documentation +47/-34

Rewrite HTTP API and scan-driver documentation

• Documents identity counts, agent fields, strict decision and execution separation, demo reset, and examples.

docs/API.md

CONNECTORS.mdDocument connector contracts and failure behavior +27/-30

Document connector contracts and failure behavior

• Adds agent identity support and clarifies MCP tools, optional capabilities, live behavior, and fixture testing.

docs/CONNECTORS.md

COSTS.mdSimplify costs, caps, and replay documentation +27/-85

Simplify costs, caps, and replay documentation

• Explains provider configuration, role models, hard caps, accounting, and credential-free replay behavior.

docs/COSTS.md

EXECUTE.mdRewrite execution and audit safety guidance +29/-89

Rewrite execution and audit safety guidance

• Clarifies intent-versus-execution, dry-run defaults, live setup, restore semantics, and ledger verification.

docs/EXECUTE.md

HARNESS.mdDefine the TrueForge and Keyring boundary +58/-37

Define the TrueForge and Keyring boundary

• Documents ownership of agent infrastructure versus governance behavior and the live and replay flows.

docs/HARNESS.md

IDENTITY.mdExtend identity documentation for AI agents +38/-23

Extend identity documentation for AI agents

• Describes exact agent matching, separation from humans and service accounts, and fixture outcomes.

docs/IDENTITY.md

POLICY.mdDocument declared agent policy +51/-41

Document declared agent policy

• Adds agent owner, purpose, identifier, tool, and risk semantics alongside existing policy sections.

docs/POLICY.md

SECURITY.mdAdd public security model +112/-0

Add public security model

• Documents trust boundaries, credential handling, redaction, append-only enforcement, deployment controls, and limitations.

docs/SECURITY.md

TEST_ORG.mdRewrite fixture organization documentation +19/-98

Rewrite fixture organization documentation

• Explains synthetic identities, planted risks, protected CI behavior, seeding, and live credential rules.

docs/TEST_ORG.md

UI.mdRewrite web workflow documentation +30/-25

Rewrite web workflow documentation

• Documents scan activity, card contents, execution, guided demo behavior, and local startup.

docs/UI.md

SKILL.mdClarify the audit skill workflow +4/-5

Clarify the audit skill workflow

• Moves the skill description into readable documentation emphasizing fan-out, reconciliation, persistence, and no revoke.

skills/keyring-audit/SKILL.md

Other (19) +1024 / -897

.gitignoreIgnore broader credential and local database artifacts +16/-4

Ignore broader credential and local database artifacts

• Expands exclusions for credential formats, private keys, embedded databases, and local infrastructure volumes.

.gitignore

.prettierignoreExclude generated local data from formatting +5/-0

Exclude generated local data from formatting

• Prevents Prettier from traversing infrastructure volumes and embedded database files.

.prettierignore

ada-lovelace.jsonRegenerate demo recording with agent identities +391/-191

Regenerate demo recording with agent identities

• Adds the sixth agent-identity system, three agent findings, identity counts, updated risks, and a nine-card queue.

fixtures/recordings/ada-lovelace.json

agent-identities.jsonAdd synthetic agent identity inventory +100/-0

Add synthetic agent identity inventory

• Defines declared Keyring agents, self-inventory evidence, and an unregistered deployment agent with live access.

fixtures/test-org/agent-identities.json

grants.jsonReplace public personal-email fixture values +6/-6

Replace public personal-email fixture values

• Moves synthetic alternate addresses under the test domain and updates evidence wording.

fixtures/test-org/grants.json

grants.materialized.jsonRefresh materialized synthetic email fixtures +6/-6

Refresh materialized synthetic email fixtures

• Aligns materialized grants and evidence with test-domain alternate addresses.

fixtures/test-org/grants.materialized.json

people.jsonMove fixture aliases to the test domain +3/-3

Move fixture aliases to the test domain

• Replaces public email-provider addresses with explicitly synthetic test-domain values.

fixtures/test-org/people.json

reconcile-input.jsonRefresh reconciliation fixture identities +15/-33

Refresh reconciliation fixture identities

• Updates alternate addresses, evidence, and compact directory formatting for synthetic data.

fixtures/test-org/reconcile-input.json

.env.exampleRequire distinct placeholder database credentials +6/-2

Require distinct placeholder database credentials

• Adds Keyring database variables and replaces predictable TrueForge password examples.

infra/.env.example

docker-compose.ymlLoad Keyring database credentials from environment +7/-6

Load Keyring database credentials from environment

• Removes hard-coded database credentials and updates health checks and startup instructions.

infra/docker-compose.yml

keyring.ymlDeclare Keyring AI agents in policy +22/-0

Declare Keyring AI agents in policy

• Adds owned, purpose-bound declarations for the reconciler and Keyring self-inventory.

keyring.yml

package.jsonRestrict formatting and upgrade Vitest +3/-3

Restrict formatting and upgrade Vitest

• Formats only tracked files and upgrades the repository test runner to Vitest 3.

package.json

list_drive_file_permissions.jsonSanitize Google permission fixture emails +3/-3

Sanitize Google permission fixture emails

• Replaces public-provider addresses with test-domain aliases.

packages/connectors/fixtures/mcp/google_workspace/list_drive_file_permissions.json

list_drive_shares_outside_org.jsonSanitize Google sharing fixture emails +3/-3

Sanitize Google sharing fixture emails

• Updates external-share records to use synthetic test-domain aliases.

packages/connectors/fixtures/mcp/google_workspace/list_drive_shares_outside_org.json

test-org-grants.jsonRefresh connector grant fixture aliases +6/-6

Refresh connector grant fixture aliases

• Aligns connector fixtures and evidence with sanitized test-domain addresses.

packages/connectors/fixtures/test-org-grants.json

package.jsonRemove unused core CLI package mapping +3/-4

Remove unused core CLI package mapping

• Normalizes package file formatting and removes the published reconcile binary mapping.

packages/core/package.json

package.jsonUpgrade Drizzle dependencies +2/-2

Upgrade Drizzle dependencies

• Updates Drizzle ORM and migration tooling to current compatible releases.

packages/server/package.json

pnpm-lock.yamlRefresh dependency lockfile +416/-606

Refresh dependency lockfile

• Locks Vitest 3, newer Drizzle packages, and their updated Vite, Rollup, and tooling dependency graph.

pnpm-lock.yaml

dataset.tsSanitize generated test organization aliases +11/-19

Sanitize generated test organization aliases

• Generates reserved-domain alternate addresses and applies formatting cleanup to fixture builders.

scripts/test-org/dataset.ts

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Self-reported status lowers risk ✓ Resolved 🐞 Bug ⛨ Security

Description

For an unmatched AI-agent grant, computeRiskScore uses the connector-supplied declarationStatus;
a source record claiming declared therefore avoids the +45 unregistered-agent penalty even when no
declared_agents policy entry matched it. This makes the supposedly highest-risk rogue-agent state
depend on unverified inventory input rather than authoritative reconciliation.

Code

packages/core/src/risk.ts[R90-94]

+  if (
+    !options.attribution &&
+    grant.principal.kind === "ai_agent" &&
+    (options.agentStatus ?? grant.principal.declarationStatus) === "unregistered"
+  ) {

Relevance

●●● Strong

Security finding conflicts with the PR’s stated goal of authoritative agent reconciliation and
rogue-agent risk handling.

PR-#7

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The connector copies record.declarationStatus directly into the grant. Approval building supplies
reconciled attribution only for clustered grants, while unknown grants have no risk attribution; the
new risk branch then falls back to that raw declaration status and penalizes only records that
self-report unregistered.

packages/connectors/src/agent-identity/connector.ts[136-161]
packages/core/src/approval-build.ts[37-69]
packages/core/src/risk.ts[84-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Unknown AI agents can evade the unregistered risk penalty by reporting `declarationStatus: declared` in connector inventory despite having no matching policy declaration.

## Issue Context
Treat a grant as declared only when reconciliation linked it to a declared-agent seed; unmatched AI-agent grants must be unregistered regardless of their raw source field.

## Fix Focus Areas
- packages/core/src/risk.ts[84-99]
- packages/core/src/approval-build.ts[37-69]
- packages/connectors/src/agent-identity/connector.ts[136-161]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Working-tree scan is disabled ✓ Resolved 🐞 Bug ⛨ Security

Description

The PR deletes ALLOW_SUBSTRINGS while scanText still references it, so every working-tree file
throws before any secret pattern is checked. Because the caller catches and ignores those errors,
uncommitted secrets can produce a successful “no secrets found” result when Git history has no hit.

Code

scripts/audit-secrets.ts[L50-55]

-const ALLOW_SUBSTRINGS = [
-  "AKIA_KEYRING_CI_ORPHAN_LOOKALIKE",
-  "example",
-  "YOUR_",
-  "placeholder",
-];

Relevance

●●● Strong

Deleted constant remains referenced, causing a deterministic ReferenceError that disables
working-tree secret scanning.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The declaration is removed by the diff, but the current branch still executes
ALLOW_SUBSTRINGS.some at the beginning of scanText. main invokes that function inside a
blanket catch, so the resulting ReferenceError is suppressed for every file and execution proceeds
to a potentially successful report.

scripts/audit-secrets.ts[86-101]
scripts/audit-secrets.ts[161-181]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Deleting `ALLOW_SUBSTRINGS` leaves an unresolved runtime reference that causes every working-tree file scan to be silently skipped.

## Issue Context
Either restore a narrowly defined synthetic-value allowlist or remove the check from `scanText`; do not swallow scanner programming errors as unreadable files.

## Fix Focus Areas
- scripts/audit-secrets.ts[50-55]
- scripts/audit-secrets.ts[86-101]
- scripts/audit-secrets.ts[161-170]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Scans drop approval cards ✓ Resolved 🐞 Bug ≡ Correctness

Description

Every fixture/live fan-out scan now truncates the reconciled card set to nine before persistence, so
grants beyond that arbitrary demo limit have no approval card and cannot be reviewed or executed.
The same truncation also affects replay and MCP scan paths, making a presentation-only constraint
alter product results.

Code

packages/server/src/services/scan-runner.ts[546]

+  cards = limitDemoCards(cards);

Relevance

●●● Strong

Recent scan-runner precedents accept correctness issues where scan fan-out or persistence loses
product results.

PR-#3

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new helper always slices the sorted card list to max, and scan-runner calls it before looping
over cards to persist approval cards and record their IDs. Thus grants are still stored, but all
cards after the first nine are absent from the scan's review workflow.

packages/server/src/agent/scan.ts[305-312]
packages/server/src/services/scan-runner.ts[543-566]
packages/server/src/services/scan-runner.ts[571-587]
packages/server/src/mcp/tools.ts[186-197]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The demo card limit is applied to the domain result before approval cards are persisted, silently omitting access-review work whenever a scan produces more than nine cards.

## Issue Context
Persist the complete card set and apply any demo-only limit in the UI or an explicitly demo-scoped serialization path.

## Fix Focus Areas
- packages/server/src/services/scan-runner.ts[543-566]
- packages/server/src/services/scan-runner.ts[739-750]
- packages/server/src/mcp/tools.ts[186-233]
- packages/server/src/agent/scan.ts[287-312]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Export signatures become unverifiable ✓ Resolved 🐞 Bug ☼ Reliability

Description

When KEYRING_EXPORT_SECRET is unset, the server signs exports with a random process-local key that
is neither exposed nor persisted, so clients cannot independently verify the signature and old
exports become unverifiable after restart. The export endpoint should fail closed without configured
key material or use a persisted signing key with an identifiable verification mechanism.

Code

packages/server/src/api/routes.ts[34]

+const exportSecret = process.env.KEYRING_EXPORT_SECRET?.trim() || randomBytes(32).toString("hex");

Relevance

●●● Strong

PR explicitly promises removal of the predictable signing fallback; random process-local keys remain
unverifiable.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

A random module-scoped secret is generated when configuration is absent, and both CSV and JSON
exports are signed with it. The only configuration reference is optional/commented, and no endpoint
or persisted state provides the generated key to a verifier.

packages/server/src/api/routes.ts[34-34]
packages/server/src/api/routes.ts[384-424]
.env.example[18-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The fallback signing key is random and process-local, making signatures unusable to external verifiers and unstable across restarts.

## Issue Context
Require `KEYRING_EXPORT_SECRET` when exporting, or persist/manage signing keys and expose a key identifier or verification contract.

## Fix Focus Areas
- packages/server/src/api/routes.ts[34-34]
- packages/server/src/api/routes.ts[384-424]
- .env.example[18-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Declared identifiers mismatch grants ✓ Resolved 🐞 Bug ≡ Correctness

Description

Declared agent and key identifiers are stored and compared verbatim, while connector grant
identifiers are normalized by trimming whitespace. A syntactically accepted policy value with
surrounding whitespace therefore fails to match its live grant, leaving the declared agent in the
unknown/unregistered path.

Code

packages/core/src/identity/reconcile.ts[R154-157]

+    const identifiers: Identifier[] = (agent.agentIds ?? [agent.id]).map((value) => ({
+      kind: "agent_id",
+      value,
+      source: "keyring.yml",

Relevance

●●● Strong

Concrete identifier normalization mismatch; local deterministic fix aligns policy values with
connector grants.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Policy-derived identifiers are inserted with raw values and looked up through exact string equality.
In contrast, createGrant applies normalizeIdentifier to all connector identifiers, and that
normalizer trims values, establishing a concrete normalization mismatch.

packages/core/src/identity/reconcile.ts[151-164]
packages/core/src/identity/reconcile.ts[195-204]
packages/core/src/identity/reconcile.ts[371-400]
packages/core/src/identifier.ts[20-25]
packages/core/src/grant.ts[153-163]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Declared-agent identifiers use different normalization from connector-generated grant identifiers, causing exact matches to fail for values with surrounding whitespace.

## Issue Context
Apply the shared identifier normalizer to policy-derived `agent_id` and `key_id` values before indexing and comparison, or reject non-normalized policy values during validation.

## Fix Focus Areas
- packages/core/src/identity/reconcile.ts[151-164]
- packages/core/src/identity/reconcile.ts[195-204]
- packages/core/src/identity/reconcile.ts[371-400]
- packages/core/src/identifier.ts[20-25]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗