Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: Test
on:
pull_request:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: python -m pip install PyYAML==6.0.1
- run: npm run build
- run: npm test
24 changes: 24 additions & 0 deletions plugins/openclaw/extra-message-policy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,3 +314,27 @@ It rechecks every file hash, takes an exclusive lock and atomically rewrites
changed JSONL files. A fresh manifest is required if ingestion changed any
file. This utility does not schedule retention, encrypt storage, process other
transcripts or backups, or prove complete deletion from those systems.


### Mandatory Discord channel scopes

`discordChannelScopes` contains `{accountId, guildId, channelIds, agentIds?}` entries.
It is an admission boundary before mutable policy rules, commands, raw sinks and
model dispatch. Exact roots and native parent metadata for their threads are
admitted. Missing provenance fails closed for protected agents/accounts. Keep
`includeThreadStarter:false`, `historyLimit:0` and thread parent-session inheritance
disabled in native configuration. Automatic quote/starter/forward contexts without
source-channel provenance reject the entire turn conservatively, including reply
attachments. Media provenance is also flattened, so protected media turns (including
ordinary attachments) are conservatively rejected. Native Discord preparation can
already have fetched supplemental media onto the host before these hooks; this
boundary protects plugin sinks and model dispatch, not that earlier transport fetch.
Plain user-written text cannot establish transport provenance.

Deploy protected guilds onto a dedicated agent, session store and controlled
workspace. Disable indexed memory/wiki, filesystem, execution and delegation tools;
permit only `search_raw_context` for archive access. Both automatic recall and that
tool enforce mandatory admission independently of caller search filters. Protected
recall accepts only new records stamped after scope admission; historical mixed
records are preserved but excluded. This does not delete historical data, provide
complete sender opt-out, or enforce restrictions on unrelated agents/guilds.
73 changes: 73 additions & 0 deletions plugins/openclaw/extra-message-policy/channel-scope.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
// Mandatory admission is independent of mutable response/ingestion policy rules.
const value = (...items) => items.find(x => typeof x === 'string' && x.trim())?.trim() || '';
const bare = x => x.replace(/^(?:channel|chat):/, '');
const snowflake = (...items) => items.map(x => bare(String(x || ''))).find(x => /^\d+$/.test(x)) || '';
export function normalizeChannelScopes(raw) {
if (raw === undefined) return [];
if (!Array.isArray(raw)) throw new Error('discordChannelScopes must be an array');
return raw.map(scope => {
if (!scope || !scope.accountId || !scope.guildId || !Array.isArray(scope.channelIds) || !scope.channelIds.length ||
!scope.channelIds.every(id => typeof id === 'string' && /^\d+$/.test(id)) ||
(scope.agentIds !== undefined && (!Array.isArray(scope.agentIds) || !scope.agentIds.every(id => typeof id === 'string' && id)))) {
throw new Error('Invalid mandatory Discord channel scope');
}
return { accountId: String(scope.accountId), guildId: String(scope.guildId), channelIds: [...new Set(scope.channelIds)], agentIds: scope.agentIds || [] };
});
}
export function scopeRoute(event = {}, ctx = {}) {
const meta = { ...event.metadata, ...ctx.metadata };
const session = value(ctx.sessionKey, ctx.SessionKey, event.sessionKey, event.SessionKey);
return {
accountId: value(ctx.accountId, ctx.AccountId, event.accountId, event.AccountId, meta.accountId),
guildId: value(ctx.rawGuildId, ctx.GroupSpace, ctx.guildId, event.rawGuildId, event.guildId, meta.rawGuildId, meta.guildId, meta.guild_id),
channelId: snowflake(ctx.NativeChannelId, ctx.ChannelId, ctx.channelId, event.channelId, event.ChannelId, meta.channelId, meta.channel_id, ctx.conversationId, event.conversationId, session.match(/:channel:([^:]+)/)?.[1]),
parentChannelId: value(ctx.parentChannelId, ctx.ParentChannelId, ctx.ThreadParentId, event.parentChannelId, meta.parentChannelId, meta.threadParentId, meta.thread_parent_id),
agentId: value(ctx.agentId, ctx.AgentId, event.agentId, session.match(/^agent:([^:]+):/)?.[1])
};
}
export function activeChannelScope(scopes = [], event = {}, ctx = {}) {
const route = scopeRoute(event, ctx);
return scopes.find(scope => scope.agentIds.includes(route.agentId) ||
(route.accountId === scope.accountId && (!route.guildId || route.guildId === scope.guildId)));
}
const externalKeys = new Set([
'ReplyToId', 'ReplyToIdFull', 'ReplyToBody', 'ReplyToSender', 'ReplyToIsQuote', 'replyToId', 'replyToIdFull', 'replyToBody', 'replyToSender', 'replyToIsQuote',
'ThreadStarterBody', 'threadStarterBody', 'starterBody', 'quote', 'quotedMessage',
'ThreadHistoryBody', 'threadHistoryBody', 'media', 'originalMedia', 'mediaStagingPending', 'MediaPath', 'MediaPaths', 'MediaUrl', 'MediaUrls', 'MediaType', 'MediaTypes', 'referenced_message', 'referencedMessage', 'message_reference', 'messageReference',
'message_snapshots', 'messageSnapshots', 'ForwardedFrom', 'ForwardedFromId', 'forwarded',
'forwardedFrom', 'replyContext', 'replyTo', 'quotedAttachments'
]);
export function hasUnverifiedSupplementalContext(...objects) {
const seen = new Set();
const visit = object => {
if (!object || typeof object !== 'object' || seen.has(object)) return false;
seen.add(object);
for (const [key, item] of Object.entries(object)) {
if (externalKeys.has(key) && item !== undefined && item !== null && item !== '' && item !== false && (!Array.isArray(item) || item.length)) return true;
if (typeof item === 'object' && visit(item)) return true;
// Discord's native forwarded envelope may already be flattened at hooks.
if (typeof item === 'string' && /\[Forwarded (?:message|content)/i.test(item)) return true;
}
return false;
};
return objects.some(visit);
}
export function admitChannelScope(scopes, event = {}, ctx = {}) {
const scope = activeChannelScope(scopes, event, ctx);
if (!scope) return { allowed: true, protected: false };
const route = scopeRoute(event, ctx);
const allowed = route.accountId === scope.accountId && route.guildId === scope.guildId &&
(scope.channelIds.includes(route.channelId) || (route.channelId && scope.channelIds.includes(route.parentChannelId))) &&
!hasUnverifiedSupplementalContext(event, ctx);
return { allowed: Boolean(allowed), protected: true, scope, route };
}
export function admittedRecallRecord(record, scopes, ctx = {}, discordOptOut = {}) {
const route = scopeRoute({}, ctx);
const scope = (scopes || []).find(s => s.agentIds.includes(route.agentId) || (route.accountId === s.accountId && route.guildId === s.guildId));
if (!scope) return true; // Preserve unrelated guild/agent recall behavior.
// Old mixed records may already contain flattened quotes. Only post-boundary
// records have the sink admission stamp; no migration invents provenance.
if (record?.channelScopeAdmission !== 1 || record.accountId !== scope.accountId || record.guildId !== scope.guildId) return false;
if (discordOptOut[scope.accountId]?.includes(record.senderId)) return false;
return admitChannelScope([scope], record, {}).allowed;
}
55 changes: 55 additions & 0 deletions plugins/openclaw/extra-message-policy/native-optout-guard.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
import { createHash } from "node:crypto";

function discordSessionRoute(sessionKey, agentId) {
if (typeof sessionKey !== "string" || typeof agentId !== "string") return;
const match = /^agent:([^:]+):discord:(direct|channel|group):([^:]+)$/.exec(sessionKey);
if (!match || match[1] !== agentId) return;
return { kind: match[2], peerId: match[3] };
}

function accountCandidates(value) {
return (Array.isArray(value) ? value : [value]).filter((account) => typeof account === "string" && account.length > 0);
}

function nativeSourceTurnId(account, target, messageId) {
if (!/^[a-z0-9][a-z0-9_-]{0,63}$/i.test(account) || !target || !messageId) return;
const digest = createHash("sha256").update(JSON.stringify([
"discord", account.trim().toLowerCase(), target, messageId
])).digest("hex");
return `channel-user:v1:${digest}`;
}

export function createNativeOptOutGuard(discordOptOut, agentAccountMap) {
const optedOut = new Map(Object.entries(discordOptOut || {}).map(([account, senders]) => [account, new Set(senders)]));
return (event = {}, ctx = {}) => {
const message = event.message;
if (message?.role !== "user") return;
const route = discordSessionRoute(ctx.sessionKey, ctx.agentId);
const channel = message.sourceChannel ?? message.provenance?.sourceChannel ?? message.__openclaw?.transport?.channel;
if (channel !== undefined ? channel !== "discord" : !route) return;
const candidates = accountCandidates(agentAccountMap?.[ctx.agentId]);
if (candidates.length === 0) return;
const senderId = message.senderId ?? message.__openclaw?.senderId ??
(route?.kind === "direct" ? route.peerId : undefined);
const sourceId = message.idempotencyKey;
const messageId = message.__openclaw?.transport?.messageId;
if (typeof sourceId === "string" && typeof messageId === "string") {
for (const account of candidates) {
const senders = optedOut.get(account);
if (!senders?.size) continue;
const target = route && route.kind !== "direct" ? `${route.kind}:${route.peerId}` : undefined;
if (target && senderId && senders.has(senderId) &&
sourceId === nativeSourceTurnId(account, target, messageId)) return { block: true };
// Main-scoped direct turns omit sender metadata. The native source ID
// still binds the bot account, direct sender, and provider message ID.
if (!route || route.kind === "direct") {
for (const sender of senders) if ((!senderId || senderId === sender) &&
sourceId === nativeSourceTurnId(account, `user:${sender}`, messageId)) return { block: true };
}
}
}
// Only a single-account agent can fall back to sender metadata. A shared
// agent needs an exact native source ID to avoid blocking the other bot.
if (candidates.length === 1 && senderId && optedOut.get(candidates[0])?.has(senderId)) return { block: true };
};
}
58 changes: 57 additions & 1 deletion plugins/openclaw/extra-message-policy/openclaw.plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,28 @@
"description": "Discord sender snowflake IDs excluded per bot account from this plugin ingestion and dispatch.",
"additionalProperties": {
"type": "array",
"items": { "type": "string", "pattern": "^[0-9]{16,22}$" },
"items": {
"type": "string",
"pattern": "^[0-9]{16,22}$"
},
"uniqueItems": true
}
},
"discordAgentAccounts": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
}
}
},
Expand Down Expand Up @@ -291,6 +310,43 @@
"$ref": "#/definitions/runtimePolicy"
}
}
},
"discordChannelScopes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"accountId",
"guildId",
"channelIds"
],
"properties": {
"accountId": {
"type": "string",
"minLength": 1
},
"guildId": {
"type": "string",
"pattern": "^[0-9]+$"
},
"channelIds": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"agentIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"definitions": {
Expand Down
8 changes: 5 additions & 3 deletions plugins/openclaw/extra-message-policy/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@nestdevlab/openclaw-plugin-extra-message-policy",
"version": "0.1.7",
"version": "0.1.9",
"private": false,
"type": "module",
"description": "OpenClaw plugin for cross-platform message ingest, response policy, and zero-embedding raw recall.",
Expand All @@ -10,7 +10,7 @@
]
},
"scripts": {
"build": "node --check index.js && node --check discord-sdk-compat.js && node --check plugin-runtime.js && node --check policy.js && node --check policy-audit.js && node --check policy-command.js && node --check native-reply.js && node --check raw-recall.js && node --check retention.js && node --check retention-cli.js && node --check runtime-context.js",
"build": "node --check index.js && node --check discord-sdk-compat.js && node --check plugin-runtime.js && node --check policy.js && node --check policy-audit.js && node --check policy-command.js && node --check native-reply.js && node --check raw-recall.js && node --check retention.js && node --check retention-cli.js && node --check runtime-context.js && node --check channel-scope.js && node --check native-optout-guard.js",
"test": "node --test",
"test:coverage": "node --test --experimental-test-coverage",
"lint": "npm run build"
Expand Down Expand Up @@ -43,7 +43,9 @@
"README.md",
"ROLLOUT.md",
"examples",
"LICENSE"
"LICENSE",
"channel-scope.js",
"native-optout-guard.js"
],
"keywords": [
"openclaw",
Expand Down
Loading
Loading