grove.protection.set()

Replace persistent host policy requiring a security extension for selected conversations.

Signature

grove.protection.set(policies: {
  target: string; protocol: string
  status: 'negotiating' | 'encrypted' | 'verified'
}[]): void

Availability

Server or query scope with all three grants: messages.protect, messages.filter.inbound, and messages.filter.outbound. Application/composer/settings and channel-bound scope cannot set policies.

Parameters

Parameter	Required	Description
`policies`	Yes	The complete active list for this extension on this network, at most 128 entries. [] removes that extension’s policies.
`target`	Yes	Conversation name (peer nickname or channel). Trimmed and capped at 128 characters; must be nonempty.
`protocol`	Yes	Nonempty protocol display label, trimmed and capped at 32 characters.
`status`	Yes	Exact negotiating, encrypted, or verified status. It is the extension’s assertion, not host verification of cryptography.

Return value

Returns undefined; no persistence acknowledgement Promise.

Behavior and errors

Policies survive the WebView stopping, crashing, timing out, and application restart. The owning filter must return a valid protect result for ordinary messages: query policies guard both directions; channel policies guard outbound only so mixed plaintext inbound traffic remains visible. Failures block protected output and can hide protected query presentation until its owner is available.

A replacement omits and removes previous entries not included in the call. Invalid/duplicate entries are skipped; do not send a partial patch or [] during initialization if protection must remain active. Removing the extension clears its policies. Explicitly register channel filters for channel policies because messages.protect defaults filters to query only.

The host stores target/protocol/status, not keys. Keep key material in secure storage. Rename events let server-scoped security runtimes move nickname-keyed state and handle collisions; implement an idempotent queryRenamed listener. Merely publishing verified does not authenticate a peer.

Example

// After your protocol has begun negotiation and registered both filters:
grove.protection.set([
  { target: 'Alice', protocol: 'OTRv3', status: 'negotiating' }
])
// Publish the complete updated list after successful peer verification.
grove.protection.set([
  { target: 'Alice', protocol: 'OTRv3', status: 'verified' }
])

See grove.filters.set(), queryRenamed, and Protected message transforms.