fix(kernel-ui): validate branded KRef values instead of unsafe casts (#921)

A follow-up to #917 addressing various items deferred during the
introduction of branded kernel identifier types.

## Summary

- Replace `as KRef` casts from unvalidated sources with runtime
validation in `kernel-ui`
- `db-parser.ts`: remove dead `?? ''` fallbacks on regex match groups,
add `insistKRef` validation for slot resolution from JSON-parsed DB
values
- `SendMessageForm.tsx`: validate user-selected target with `isKRef`
before sending, replacing the blind `as KRef` cast
- Add `isKRef`, `insistKRef`, `KRefStruct` to `setupOcapKernelMock` test
utility
- Includes prior commit addressing PR review feedback on branded types
in `ocap-kernel`

## Test plan

- [x] `yarn workspace @metamask/kernel-ui run build` passes
- [x] `yarn workspace @metamask/kernel-ui test:dev:quiet` passes (all 34
test files, 263 tests)

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds runtime `KRef` validation in UI and DB parsing paths, which can
now reject/throw on previously accepted malformed values. Risk is
moderate because it changes input handling and parsing behavior but is
narrowly scoped and covered by updated tests.
> 
> **Overview**
> **Hardens branded identifier handling** by validating `KRef` values at
runtime instead of relying on unchecked `as KRef` casts.
> 
> In `SendMessageForm`, the selected target is now stored as `KRef |
null`, validated via `isKRef` on change, and sending is blocked when the
target is invalid; tests are updated accordingly and add coverage for
failed `KRef` validation.
> 
> In `kernel-ui`’s `db-parser`, regex match fallbacks are removed and
`resolveSlot` now calls `insistKRef` when converting JSON-parsed slot
strings, making malformed DB data fail fast. Supporting changes extend
`setupOcapKernelMock` with `isKRef`/`insistKRef`/`KRefStruct`, and
`ocap-kernel` tests/docs are updated (including new `getKnownRelays`
test coverage and tighter ID validation cases).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
55a981a. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rekmarks

packages/kernel-ui/src/components/SendMessageForm.test.tsx

@@ -17,7 +17,7 @@ import { useRegistry } from '../hooks/useRegistry.ts';
 import type { ObjectRegistry } from '../types.ts';
 import { SendMessageForm } from './SendMessageForm.tsx';
 
-setupOcapKernelMock();
+const { setMockBehavior } = setupOcapKernelMock();
 
 vi.mock('../context/PanelContext.tsx', () => ({
   usePanelContext: vi.fn(),
@@ -27,7 +27,8 @@ vi.mock('../hooks/useRegistry.ts', () => ({
   useRegistry: vi.fn(),
 }));
 
-vi.mock('@metamask/kernel-utils', () => ({
+vi.mock('@metamask/kernel-utils', async (importOriginal) => ({
+  ...(await importOriginal()),
   stringify: vi.fn(),
 }));
 
@@ -45,14 +46,14 @@ describe('SendMessageForm Component', () => {
         overview: { name: 'TestVat1', bundleSpec: '' },
         ownedObjects: [
           {
-            kref: 'kref1',
+            kref: 'ko1',
             eref: 'eref1',
             refCount: '1',
             toVats: [],
             revoked: 'false',
           },
           {
-            kref: 'kref2',
+            kref: 'ko2',
             eref: 'eref2',
             refCount: '1',
             toVats: [],
@@ -67,7 +68,7 @@ describe('SendMessageForm Component', () => {
         overview: { name: 'TestVat2', bundleSpec: '' },
         ownedObjects: [
           {
-            kref: 'kref3',
+            kref: 'ko3',
             eref: 'eref3',
             refCount: '1',
             toVats: [],
@@ -76,7 +77,7 @@ describe('SendMessageForm Component', () => {
         ],
         importedObjects: [
           {
-            kref: 'kref4',
+            kref: 'ko4',
             eref: 'eref4',
             refCount: '1',
             fromVat: 'vat1',
@@ -144,19 +145,19 @@ describe('SendMessageForm Component', () => {
     expect(options).toHaveLength(5); // 1 placeholder + 4 options from mock registry
 
     // Check dropdown options include objects from the registry
-    expect(screen.getByText('kref1 (TestVat1)')).toBeInTheDocument();
-    expect(screen.getByText('kref2 (TestVat1)')).toBeInTheDocument();
-    expect(screen.getByText('kref3 (TestVat2)')).toBeInTheDocument();
-    expect(screen.getByText('kref4 (TestVat1)')).toBeInTheDocument();
+    expect(screen.getByText('ko1 (TestVat1)')).toBeInTheDocument();
+    expect(screen.getByText('ko2 (TestVat1)')).toBeInTheDocument();
+    expect(screen.getByText('ko3 (TestVat2)')).toBeInTheDocument();
+    expect(screen.getByText('ko4 (TestVat1)')).toBeInTheDocument();
   });
 
   it('updates form values when inputs change', async () => {
     const { getByTestId } = render(<SendMessageForm />);
 
     // Change target
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
-    expect(targetSelect).toHaveValue('kref1');
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
+    expect(targetSelect).toHaveValue('ko1');
 
     // Change method
     const methodInput = getByTestId('message-method');
@@ -179,7 +180,7 @@ describe('SendMessageForm Component', () => {
 
     // Select a target
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     // Button should now be enabled
     expect(sendButton).not.toBeDisabled();
@@ -192,12 +193,26 @@ describe('SendMessageForm Component', () => {
     expect(sendButton).toBeDisabled();
   });
 
+  it('does not set target when value fails KRef validation', async () => {
+    setMockBehavior({ isKRef: false });
+    const { getByTestId } = render(<SendMessageForm />);
+
+    const targetSelect = getByTestId('message-target');
+    fireEvent.change(targetSelect, { target: { value: 'not-a-kref' } });
+
+    // Target should remain unset, button stays disabled
+    expect(targetSelect).toHaveValue('');
+    expect(getByTestId('message-send-button')).toBeDisabled();
+
+    setMockBehavior({ isKRef: true });
+  });
+
   it('calls callKernelMethod with correct parameters when Send button is clicked', async () => {
     const { getByTestId } = render(<SendMessageForm />);
 
     // Set up form values
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     const methodInput = getByTestId('message-method');
     fireEvent.change(methodInput, { target: { value: 'testMethod' } });
@@ -215,7 +230,7 @@ describe('SendMessageForm Component', () => {
     // Check if callKernelMethod was called with correct parameters
     expect(callKernelMethod).toHaveBeenCalledWith({
       method: 'queueMessage',
-      params: ['kref1', 'testMethod', expectedArgs],
+      params: ['ko1', 'testMethod', expectedArgs],
     });
 
     // Check if fetchObjectRegistry was called
@@ -232,7 +247,7 @@ describe('SendMessageForm Component', () => {
 
     // Set up form values and submit
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     const sendButton = getByTestId('message-send-button');
     await userEvent.click(sendButton);
@@ -255,7 +270,7 @@ describe('SendMessageForm Component', () => {
 
     // Set up form values and submit
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     const sendButton = getByTestId('message-send-button');
     await userEvent.click(sendButton);
@@ -277,7 +292,7 @@ describe('SendMessageForm Component', () => {
 
     // Set up form values with invalid JSON
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     const paramsInput = getByTestId('message-params');
     fireEvent.change(paramsInput, { target: { value: 'invalid json' } });
@@ -300,7 +315,7 @@ describe('SendMessageForm Component', () => {
 
     // Set up form values - we need a valid target and valid JSON
     const targetSelect = getByTestId('message-target');
-    fireEvent.change(targetSelect, { target: { value: 'kref1' } });
+    fireEvent.change(targetSelect, { target: { value: 'ko1' } });
 
     // Ensure we have valid JSON in the params field
     const paramsInput = getByTestId('message-params');

packages/kernel-ui/src/components/SendMessageForm.tsx

@@ -9,6 +9,7 @@ import {
   TextColor,
 } from '@metamask/design-system-react';
 import { stringify } from '@metamask/kernel-utils';
+import { isKRef } from '@metamask/ocap-kernel';
 import type { KRef } from '@metamask/ocap-kernel';
 import type { Json } from '@metamask/utils';
 import { useState, useMemo } from 'react';
@@ -27,7 +28,7 @@ const inputStyle =
 export const SendMessageForm: React.FC = () => {
   const { callKernelMethod, logMessage, objectRegistry } = usePanelContext();
   const { fetchObjectRegistry } = useRegistry();
-  const [target, setTarget] = useState('');
+  const [target, setTarget] = useState<KRef | null>(null);
   const [method, setMethod] = useState('__getMethodNames__');
   const [paramsText, setParamsText] = useState('[]');
   const [result, setResult] = useState<Json | null>(null);
@@ -64,12 +65,15 @@ export const SendMessageForm: React.FC = () => {
   }, [objectRegistry]);
 
   const handleSend = (): void => {
+    if (!target) {
+      return;
+    }
     Promise.resolve()
       .then(() => JSON.parse(paramsText) as Json[])
       .then(async (args) =>
         callKernelMethod({
           method: 'queueMessage',
-          params: [target as KRef, method, args],
+          params: [target, method, args],
         }),
       )
       .then((response) => {
@@ -117,8 +121,11 @@ export const SendMessageForm: React.FC = () => {
           </label>
           <select
             id="message-target"
-            value={target}
-            onChange={(event) => setTarget(event.target.value)}
+            value={target ?? ''}
+            onChange={(event) => {
+              const { value } = event.target;
+              setTarget(isKRef(value) ? value : null);
+            }}
             data-testid="message-target"
             className={`${inputStyle} cursor-pointer`}
           >
@@ -172,7 +179,7 @@ export const SendMessageForm: React.FC = () => {
             variant={ButtonVariant.Primary}
             size={ButtonSize.Sm}
             onClick={handleSend}
-            isDisabled={!(target.trim() && method.trim())}
+            isDisabled={!(target && method.trim())}
             className="h-9 rounded-md"
             data-testid="message-send-button"
           >

packages/kernel-ui/src/services/db-parser.ts

@@ -1,3 +1,4 @@
+import { insistKRef } from '@metamask/ocap-kernel';
 import type { KRef } from '@metamask/ocap-kernel';
 
 import type {
@@ -79,17 +80,19 @@ export function parseObjectRegistry(
     if ((matches = key.match(/^(v\d+)\.c\.(ko\d+)$/u))) {
       matches[1] &&
         objCList.push({
-          vat: matches[1] ?? '',
-          kref: (matches[2] ?? '') as KRef,
+          vat: matches[1],
+          // Safe cast: regex capture group guarantees KRef format
+          kref: matches[2] as KRef,
           eref: value.replace(/^R\s*/u, ''),
         });
       continue;
     }
     if ((matches = key.match(/^(v\d+)\.c\.(kp\d+)$/u))) {
       matches[1] &&
         prmCList.push({
-          vat: matches[1] ?? '',
-          kref: (matches[2] ?? '') as KRef,
+          vat: matches[1],
+          // Safe cast: regex capture group guarantees KRef format
+          kref: matches[2] as KRef,
           eref: value.replace(/^R\s*/u, ''),
         });
       continue;
@@ -113,9 +116,10 @@ export function parseObjectRegistry(
 
   // Helper to resolve slots
   const resolveSlot = (kref: string): SlotInfo => {
+    insistKRef(kref);
     const entry = objCList.find((item) => item.kref === kref);
     return {
-      kref: kref as KRef,
+      kref,
       eref: entry?.eref ?? null,
       vat: entry?.vat ?? null,
     };

packages/ocap-kernel/src/store/README.md

@@ -2,8 +2,10 @@
 
 The kernel store (`makeKernelStore` in `index.ts`) wraps the raw
 `KernelDatabase` from `@metamask/kernel-store` and exposes typed methods for
-all kernel-state access. Raw `kv` is intentionally not exposed — all reads and
-writes go through these methods to preserve branded type safety.
+all kernel-state access. The raw `kv` store is not exposed through
+`KernelStore` — production code reads and writes go through typed methods to
+preserve branded type safety. (Test code may access `database.kernelKVStore`
+directly.)
 
 ## Data integrity
 
@@ -35,7 +37,8 @@ Validated writes are the first line of defense:
 
 - All values entering the store pass through typed store methods or validated
   constructors (e.g., `makeGCAction()`).
-- Migration correctness: schema changes must transform all affected keys.
+- Any future schema migrations must transform all affected keys to maintain
+  typed invariants.
 
 See the trust model documentation at the top of `../types.ts` for how branded
 types are validated at other boundaries (external input, translators, internal

packages/ocap-kernel/src/store/index.test.ts

@@ -522,4 +522,33 @@ describe('kernel store', () => {
       expect(preserved).toBe(original);
     });
   });
+
+  describe('getKnownRelays', () => {
+    it('returns empty array when no relays are stored', () => {
+      const ks = makeKernelStore(mockKernelDatabase);
+      expect(ks.getKnownRelays()).toStrictEqual([]);
+    });
+
+    it('returns stored relays', () => {
+      const ks = makeKernelStore(mockKernelDatabase);
+      ks.setKnownRelays(['peer1', 'peer2']);
+      expect(ks.getKnownRelays()).toStrictEqual(['peer1', 'peer2']);
+    });
+
+    it('throws when stored knownRelays is not a JSON array', () => {
+      const ks = makeKernelStore(mockKernelDatabase);
+      mockKernelDatabase.kernelKVStore.set('knownRelays', '"not-an-array"');
+      expect(() => ks.getKnownRelays()).toThrow(
+        'knownRelays must be an array of strings',
+      );
+    });
+
+    it('throws when stored knownRelays contains non-string entries', () => {
+      const ks = makeKernelStore(mockKernelDatabase);
+      mockKernelDatabase.kernelKVStore.set('knownRelays', '[1, 2, 3]');
+      expect(() => ks.getKnownRelays()).toThrow(
+        'knownRelays must be an array of strings',
+      );
+    });
+  });
 });

packages/ocap-kernel/src/types.test.ts

@@ -429,6 +429,8 @@ describe('isVatId', () => {
     { name: 'missing number part', value: 'v' },
     { name: 'non-numeric suffix', value: 'va' },
     { name: 'mixed suffix', value: 'v1a' },
+    { name: 'float suffix', value: 'v1.5' },
+    { name: 'negative', value: 'v-1' },
     { name: 'number', value: 123 },
     { name: 'null', value: null },
   ])('returns false for $name', ({ value }) => {
@@ -745,6 +747,7 @@ describe('insistGCAction', () => {
   it.each([
     { name: 'invalid format', value: 'invalid' },
     { name: 'invalid vatId', value: 'invalid dropExport ko123' },
+    { name: 'invalid action type', value: 'v1 invalidAction ko123' },
     { name: 'number', value: 123 },
   ])('throws for $name', ({ value }) => {
     expect(() => insistGCAction(value)).toThrow('not a valid GCAction');

packages/ocap-kernel/src/vats/VatHandle.test.ts

@@ -11,7 +11,12 @@ import type { MockInstance } from 'vitest';
 import type { KernelQueue } from '../KernelQueue.ts';
 import { makeKernelStore } from '../store/index.ts';
 import type { KernelStore } from '../store/index.ts';
-import type { VRef, EndpointMessage, VatDeliveryResult } from '../types.ts';
+import type {
+  VRef,
+  ERef,
+  EndpointMessage,
+  VatDeliveryResult,
+} from '../types.ts';
 import { VatHandle } from './VatHandle.ts';
 import { makeMapKernelDatabase } from '../../test/storage.ts';
 
@@ -147,10 +152,10 @@ describe('VatHandle', () => {
       sendVatCommandMock.mockReset();
       const mockResult: VatDeliveryResult = [[[], []], null];
       sendVatCommandMock.mockResolvedValueOnce(mockResult);
-      const target = 'kp1' as VRef;
+      const target = 'o+0' as VRef;
       const message: EndpointMessage = {
         methargs: { body: '["arg1","arg2"]', slots: [] },
-        result: 'kp123',
+        result: 'p+1' as ERef,
       };
       await vat.deliverMessage(target, message);
       expect(sendVatCommandMock).toHaveBeenCalledTimes(1);