@canonmsg/backend-contracts 2.0.0 → 2.2.0

package/dist/cjs/diffRedaction.js

@@ -0,0 +1,73 @@
+"use strict";
+// Sensitive-content protection for approval diffs.
+//
+// Approval diffs include PRE-IMAGE context lines and ride on a message readable
+// by every conversation member, so a secret-bearing file would leak existing
+// secrets. The emitting host applies this before sending (it owns the file
+// context); the server (@canonmsg/functions) mirrors the same suppression
+// defensively. Single-sourced here in the zero-dependency backend-contracts
+// leaf so @canonmsg/core (client-side sanitizer) and Functions (server mirror)
+// share one implementation — Functions deliberately does not depend on core.
+//
+// Two deliberately narrow mechanisms so ordinary code diffs stay readable:
+//   1. Path suppression — files whose path screams "secret store" lose their
+//      hunk text entirely; entry/status/counts survive.
+//   2. High-confidence token redaction — prefix-anchored credential shapes
+//      (AWS/GitHub/Slack/Google/OpenAI-style keys, JWTs) are replaced with
+//      `[redacted]` inside remaining hunks. Private-key blocks suppress the
+//      whole file (redacting a PEM body line-by-line is fragile).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIVATE_KEY_BLOCK = void 0;
+exports.isSensitiveDiffPath = isSensitiveDiffPath;
+exports.redactSecretTokens = redactSecretTokens;
+const SENSITIVE_DIFF_BASENAME_PATTERNS = [
+    /^\.env(\..+)?$/i,
+    /^\.npmrc$/i,
+    /^\.netrc$/i,
+    /^\.pgpass$/i,
+    /^\.git-credentials$/i,
+    /^\.htpasswd$/i,
+    /\.(pem|key|p12|pfx|keystore|jks|tfvars)$/i,
+    /^id_(rsa|dsa|ecdsa|ed25519)(\..+)?$/i,
+    // Word-bounded so "secrets.json" and "client_secret.yaml" match but
+    // "secretary.ts" does not.
+    /(^|[-_.])(credentials?|secrets?)([-_.]|$)/i,
+    /^serviceaccount.*\.json$/i,
+    /^kubeconfig(\..+)?$/i,
+];
+// Directory components that mark everything beneath them sensitive
+// (~/.ssh/config, .aws/credentials, infra/secrets/db.yaml, …).
+const SENSITIVE_DIFF_SEGMENT_PATTERNS = [
+    /^\.ssh$/i,
+    /^\.aws$/i,
+    /^\.gnupg$/i,
+    /^\.kube$/i,
+    /^secrets?$/i,
+    /^credentials?$/i,
+];
+const SECRET_TOKEN_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/g,
+    /gh[pousr]_[A-Za-z0-9]{36,255}/g,
+    /github_pat_[A-Za-z0-9_]{22,255}/g,
+    /xox[baprs]-[A-Za-z0-9-]{10,250}/g,
+    /AIza[0-9A-Za-z_-]{35}/g,
+    /sk-[A-Za-z0-9_-]{20,250}/g,
+    /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+];
+/** Matches the header line of a PEM private-key block. */
+exports.PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY( BLOCK)?-----/;
+/** True when a diff file path (or rename source) matches the sensitive list. */
+function isSensitiveDiffPath(path) {
+    const segments = path.split('/').filter(Boolean);
+    const basename = segments.pop() ?? path;
+    return SENSITIVE_DIFF_BASENAME_PATTERNS.some((pattern) => pattern.test(basename))
+        || segments.some((segment) => SENSITIVE_DIFF_SEGMENT_PATTERNS.some((pattern) => pattern.test(segment)));
+}
+/** Replace high-confidence credential shapes inside hunk text with `[redacted]`. */
+function redactSecretTokens(text) {
+    let redacted = text;
+    for (const pattern of SECRET_TOKEN_PATTERNS) {
+        redacted = redacted.replace(pattern, '[redacted]');
+    }
+    return redacted;
+}

package/dist/cjs/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./diffRedaction.js"), exports);
 __exportStar(require("./media.js"), exports);
 __exportStar(require("./message.js"), exports);
 __exportStar(require("./runtimeCardFields.js"), exports);
@@ -21,3 +22,6 @@ __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
 __exportStar(require("./contactRequest.js"), exports);
+__exportStar(require("./verbContract.js"), exports);
+__exportStar(require("./verbSchemas.js"), exports);
+__exportStar(require("./verbWire.js"), exports);

package/dist/cjs/message.js

@@ -61,7 +61,8 @@ function normalizeContentType(value) {
         || value === 'audio'
         || value === 'video'
         || value === 'file'
-        || value === 'contact_card') {
+        || value === 'contact_card'
+        || value === 'interaction') {
         return value;
     }
     throw new Error('Message is missing canonical contentType');
@@ -110,6 +111,41 @@ function normalizeContactCard(value) {
         card.lifecycleState = value.lifecycleState;
     return card;
 }
+const INTERACTION_KINDS = [
+    'contact', 'approval', 'input', 'plan', 'card',
+];
+function normalizeInteraction(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (!INTERACTION_KINDS.includes(value.kind))
+        return undefined;
+    if (typeof value.requestId !== 'string' || value.requestId.length === 0)
+        return undefined;
+    const envelope = {
+        kind: value.kind,
+        requestId: value.requestId,
+        interactive: value.interactive === true,
+    };
+    if (typeof value.responseUserId === 'string')
+        envelope.responseUserId = value.responseUserId;
+    if (typeof value.expiresAt === 'string')
+        envelope.expiresAt = value.expiresAt;
+    if (typeof value.schemaVersion === 'string')
+        envelope.schemaVersion = value.schemaVersion;
+    if (isRecord(value.preview)) {
+        const preview = {};
+        if (typeof value.preview.title === 'string')
+            preview.title = value.preview.title;
+        if (Array.isArray(value.preview.blockKinds)) {
+            preview.blockKinds = value.preview.blockKinds.filter((entry) => typeof entry === 'string');
+        }
+        envelope.preview = preview;
+    }
+    if (isRecord(value.response)) {
+        envelope.response = value.response;
+    }
+    return envelope;
+}
 function serializeStoredMessage(input) {
     const { data } = input;
     const attachments = data.attachments === undefined
@@ -153,6 +189,13 @@ function serializeStoredMessage(input) {
     if (runtimeCard) {
         result.runtimeCard = runtimeCard;
     }
+    const interaction = normalizeInteraction(data.interaction);
+    if (interaction) {
+        result.interaction = interaction;
+    }
+    if (typeof data.body === 'string') {
+        result.body = data.body;
+    }
     const reactions = normalizeReactions(data.reactions);
     if (reactions) {
         result.reactions = reactions;

package/dist/cjs/verbContract.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * Canon agent verb contract — the canonical, runtime-agnostic vocabulary for
+ * the conversational/HITL actions an agent deliberately takes against Canon
+ * (v1 scope: messaging, HITL interactions, contact sharing, and the read
+ * verbs bindings need alongside them).
+ *
+ * One verb = one intent-level action. Each runtime binding (Hermes native
+ * tool, MCP server, codex dynamicTools, agent-sdk method, CLI) projects these
+ * verbs into its native tool surface; the names, argument shapes, limits, and
+ * result vocabularies defined here are the single source of truth. JSON
+ * Schemas for each verb live in `verbSchemas.ts` and are also emitted as a
+ * plain JSON artifact at build time (`dist/canon-verbs.schema.json`) so
+ * non-TypeScript consumers (the Python hermes plugin, external integrators)
+ * can consume the identical contract.
+ *
+ * Deliberately NOT verbs: replying in the active conversation, streaming
+ * partials, typing, and read receipts stay host-mediated — the model talks
+ * and the platform delivers. Still out of scope pending their own design
+ * pass: plan approval (the fourth runtime-interaction kind — coding-host
+ * concern today) and block/mute. Their REST surfaces remain directly
+ * callable.
+ *
+ * Scope note: this module DESCRIBES the contract (canonical shapes + the
+ * server-enforced limits, with enforcement sites cited). Enforcement itself
+ * stays where it runs today — functions/src. Server-side verb endpoints that
+ * validate against these schemas are a planned follow-up.
+ *
+ * Normativity: the JSON Schemas in `verbSchemas.ts` (and the emitted
+ * canon-verbs.schema.json) are the normative contract. The TypeScript types
+ * here are a convenience projection — corrections flow schema -> type, and
+ * the dual-witness fixtures in verbContract.test.ts (each fixture is both
+ * compile-checked against the type and validated against the schema) guard
+ * the two from drifting. Single-sourcing the types from the schemas is a
+ * planned follow-up.
+ *
+ * Byte-sensitive limits: JSON Schema `maxLength` counts UTF-16 code units,
+ * but several server limits count UTF-8 bytes or serialized-JSON length,
+ * which no standard keyword expresses. Bindings MUST run
+ * `findVerbByteLimitViolations()` (or equivalent checks from the emitted
+ * canon-verbs.limits.json) after schema validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANON_VERB_LIMITS_ARTIFACT = exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = exports.CANON_VERB_NAMES = exports.SELF_CONTEXT_TYPE = exports.VERB_RATE_LIMITS = exports.VERB_LIMITS = exports.VERB_ID_PATTERNS = exports.CANON_CARD_SCHEMA_ID = exports.CANON_VERB_NAMESPACE = exports.CANON_VERBS_SCHEMA_ID = exports.CANON_VERBS_SCHEMA_VERSION = void 0;
+exports.canonVerbToolName = canonVerbToolName;
+exports.findVerbByteLimitViolations = findVerbByteLimitViolations;
+/** Identifier for this contract document. */
+exports.CANON_VERBS_SCHEMA_VERSION = 'canon.verbs.v1';
+/** $id of the emitted JSON Schema bundle. */
+exports.CANON_VERBS_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.verbs.v1.json';
+/** Namespace prefix bindings should use for flat tool names (e.g. `canon_send_to`). */
+exports.CANON_VERB_NAMESPACE = 'canon';
+/**
+ * $id of the canonical canon.card.v1 document schema
+ * (@canonmsg/rich-cards RUNTIME_CARD_JSON_SCHEMA_V1). The verbs bundle only
+ * validates the card ENVELOPE; compose the full document schema into card
+ * verbs via `getVerbInputSchema(verb, { cardSchema })`.
+ */
+exports.CANON_CARD_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.card.v1.json';
+/**
+ * Identifier patterns, mirrored from the enforcing sites:
+ * - RUNTIME_ID_PATTERN: conversation/input/approval ids —
+ *   functions/src/utils/runtimeRequestHelpers.ts (`/^[A-Za-z0-9_.:-]{1,160}$/`)
+ * - CARD_ID_PATTERN / ACTION_ID_PATTERN: functions/src/api/interactionCard.ts
+ *   and @canonmsg/rich-cards RUNTIME_CARD_ACTION_ID_PATTERN (80 chars)
+ * - QUESTION_ID_PATTERN: functions/src/api/interactionInput.ts (120 chars)
+ * - SESSION_RULE_TOOL_PATTERN: functions/src/callable/respondToInteraction.ts
+ */
+exports.VERB_ID_PATTERNS = {
+    runtimeId: '^[A-Za-z0-9_.:-]{1,160}$',
+    cardId: '^[A-Za-z0-9_.:-]{1,80}$',
+    actionId: '^[A-Za-z0-9_.:-]{1,80}$',
+    questionId: '^[A-Za-z0-9_.:-]{1,120}$',
+    sessionRuleToolPattern: '^[\\w.*:-]{1,128}$',
+};
+/**
+ * Server-enforced limits, single-sourced. Each value cites its enforcement
+ * site; keep the citation current when a limit moves.
+ */
+exports.VERB_LIMITS = {
+    /** Message text — UTF-8 bytes (functions/src/api/sendMessage.ts MAX_MESSAGE_TEXT_BYTES). */
+    messageTextBytes: 4096,
+    /**
+     * Serialized metadata JSON length in UTF-16 code units — the server checks
+     * JSON.stringify(metadata).length, not bytes (sendMessage.ts:716-724 inline;
+     * parseBody.ts maxJsonBytes despite the name).
+     */
+    messageMetadataJsonChars: 4096,
+    /** Attachments per message (sendMessage.ts MAX_MESSAGE_ATTACHMENTS). */
+    messageAttachments: 10,
+    /** Client-supplied messageId — chars and UTF-8 bytes (sendMessage.ts). */
+    messageIdChars: 160,
+    messageIdBytes: 256,
+    /** Self-context note (functions/src/utils/selfContexts.ts SELF_CONTEXT_CONTEXT_LIMIT). */
+    selfContextChars: 1000,
+    /**
+     * Contact-request note. Values longer than this are truncated by senders
+     * (slice(0,497)+'...') — the truncation is currently triplicated in
+     * functions/src/api/sendContextualMessage.ts, packages/core/src/reach-out.ts
+     * and the hermes plugin; this constant is the canonical figure.
+     */
+    contactRequestNoteChars: 500,
+    /** Group membership cap incl. creator (functions/src/utils/conversations.ts MAX_GROUP_MEMBERS). */
+    groupMembers: 50,
+    /** Runtime input (functions/src/api/interactionInput.ts). */
+    inputTitleChars: 160,
+    inputPromptChars: 4000,
+    inputChoices: 12,
+    inputChoiceLabelChars: 120,
+    inputChoiceValueChars: 200,
+    inputChoiceDescriptionChars: 300,
+    inputQuestions: 12,
+    inputQuestionChars: 1000,
+    inputQuestionHeaderChars: 120,
+    inputSecretNameChars: 160,
+    inputAnswerChars: 8192,
+    /** Approval (functions/src/api/interactionApproval.ts). */
+    toolNameChars: 128,
+    toolSummaryChars: 1000,
+    approvalDetails: 8,
+    approvalDetailLabelChars: 80,
+    approvalDetailValueChars: 500,
+    diffFiles: 100,
+    diffPathChars: 1024,
+    diffFileBytes: 24 * 1024,
+    diffTotalBytes: 96 * 1024,
+    /** Card envelope acceptance (functions/src/api/interactionCard.ts — server caps;
+     * authoring caps in @canonmsg/rich-cards are stricter: title 120, fallback 500, blocks 24). */
+    cardEnvelopeBytes: 32 * 1024,
+    cardServerTitleChars: 200,
+    cardServerFallbackTextChars: 2000,
+    cardServerBlocks: 64,
+    /** Response-values caps enforced on submit (callable respondToInteraction.ts
+     * MAX_VALUES_BYTES/MAX_VALUES_DEPTH; interactionCard.ts re-checks bytes on
+     * consume via MAX_REPLY_BYTES). */
+    cardValuesBytes: 8 * 1024,
+    cardValuesDepth: 8,
+    /** Native correlation metadata (functions/src/api/interactionKinds.ts normalizeNative). */
+    nativeKeys: 24,
+    nativeValueChars: 256,
+    nativeHandles: 16,
+    /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
+    minTimeoutMs: 1000,
+    /** input/card/plan ceiling (30 minutes). */
+    maxTimeoutMs: 30 * 60 * 1000,
+    /** approval-only ceiling (72 hours — owner ruling 2026-07-10). */
+    maxApprovalTimeoutMs: 72 * 60 * 60 * 1000,
+    /** turnId / runtimeId fields on interaction creators. */
+    turnIdChars: 128,
+    /** Reaction key (functions/src/api/reactToMessage.ts normalizeReactionKey). */
+    reactionEmojiChars: 64,
+    /**
+     * Group name authoring cap (enforced on rename via updateNameServer; group
+     * CREATE does not length-check today — treat as the authoring contract).
+     */
+    groupNameChars: 100,
+};
+/**
+ * Sender-side rate limits enforced by POST /messages/send
+ * (functions/src/api/sendMessage.ts). Bindings should surface 429s with the
+ * retryAfter the server returns rather than re-deriving these.
+ */
+exports.VERB_RATE_LIMITS = {
+    senderMessagesPer5Min: 300,
+    conversationMessagesPer5Min: 120,
+    agentPeerMessagesPerHour: 30,
+};
+/** The one self-context type the platform accepts today. */
+exports.SELF_CONTEXT_TYPE = 'cross_session';
+/** Canonical verb names. */
+exports.CANON_VERB_NAMES = [
+    'send_to',
+    'request_input',
+    'request_approval',
+    'check_approval',
+    'send_card',
+    'request_card',
+    'share_contact',
+    'react',
+    'forward',
+    'create_group',
+    'add_member',
+    'remove_member',
+    'leave_conversation',
+    'list_contacts',
+    'list_contact_requests',
+    'list_conversations',
+];
+/**
+ * Error code on the 400 a create_group receives when NO member is directly
+ * addable (approval-required members can only be invited to an existing
+ * group; a creator-only group is not created). The error detail carries the
+ * partition: pendingRequired[] and skipped[].
+ */
+exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = 'CREATE_GROUP_NO_ADDABLE_MEMBERS';
+/**
+ * Error code on the 403 a create_group receives when the CREATOR itself is
+ * a coding agent requiring explicit session setup: the group helper prepares
+ * session configs for every coding-agent member including the creator, and
+ * only the agent's human owner may provide them (v1 scoping — the owner
+ * creates the group from the app instead).
+ */
+exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = 'CREATE_GROUP_CREATOR_SETUP_REQUIRED';
+/** Flat tool name for a verb on namespaced tool surfaces (e.g. `canon_send_to`). */
+function canonVerbToolName(verb) {
+    return `${exports.CANON_VERB_NAMESPACE}_${verb}`;
+}
+const utf8Bytes = (value) => new TextEncoder().encode(value).length;
+function checkTextBytes(path, value, into) {
+    if (typeof value === 'string' && utf8Bytes(value) > exports.VERB_LIMITS.messageTextBytes) {
+        into.push({
+            path,
+            message: `text exceeds ${exports.VERB_LIMITS.messageTextBytes} UTF-8 bytes (sendMessage.ts MAX_MESSAGE_TEXT_BYTES)`,
+        });
+    }
+}
+function checkMessageId(path, value, into) {
+    if (typeof value === 'string' && utf8Bytes(value) > exports.VERB_LIMITS.messageIdBytes) {
+        into.push({
+            path,
+            message: `messageId exceeds ${exports.VERB_LIMITS.messageIdBytes} UTF-8 bytes (sendMessage.ts MAX_MESSAGE_ID_BYTES)`,
+        });
+    }
+}
+/**
+ * The server limits JSON Schema cannot express: UTF-8 byte caps and
+ * serialized-JSON length caps. Bindings MUST run this after schema
+ * validation; the server enforces the same checks with 400s.
+ */
+function findVerbByteLimitViolations(verb, input) {
+    const violations = [];
+    if (verb === 'send_to' || verb === 'share_contact' || verb === 'forward') {
+        checkTextBytes('text', input.text, violations);
+    }
+    if (verb === 'share_contact') {
+        checkMessageId('messageId', input.messageId, violations);
+    }
+    if (verb === 'send_to') {
+        const options = input.messageOptions;
+        if (options && typeof options === 'object' && !Array.isArray(options)) {
+            const record = options;
+            checkMessageId('messageOptions.messageId', record.messageId, violations);
+            if (record.metadata !== undefined) {
+                const serialized = JSON.stringify(record.metadata);
+                if (typeof serialized === 'string' && serialized.length > exports.VERB_LIMITS.messageMetadataJsonChars) {
+                    violations.push({
+                        path: 'messageOptions.metadata',
+                        message: `metadata serializes to more than ${exports.VERB_LIMITS.messageMetadataJsonChars} JSON characters `
+                            + '(sendMessage.ts checks JSON.stringify length)',
+                    });
+                }
+            }
+        }
+    }
+    if (verb === 'send_card' || verb === 'request_card') {
+        if (input.card !== undefined) {
+            const serialized = JSON.stringify(input.card);
+            if (typeof serialized === 'string' && utf8Bytes(serialized) > exports.VERB_LIMITS.cardEnvelopeBytes) {
+                violations.push({
+                    path: 'card',
+                    message: `card serializes to more than ${exports.VERB_LIMITS.cardEnvelopeBytes} bytes (interactionCard.ts MAX_CARD_BYTES)`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Machine-readable limits companion to the schema bundle, emitted as
+ * dist/canon-verbs.limits.json so non-TypeScript bindings can apply the
+ * byte-sensitive checks JSON Schema cannot express.
+ */
+exports.CANON_VERB_LIMITS_ARTIFACT = {
+    schemaVersion: exports.CANON_VERBS_SCHEMA_VERSION,
+    limits: exports.VERB_LIMITS,
+    rateLimits: exports.VERB_RATE_LIMITS,
+    idPatterns: exports.VERB_ID_PATTERNS,
+    byteSemantics: {
+        'send_to.text': 'utf8_bytes<=messageTextBytes',
+        'share_contact.text': 'utf8_bytes<=messageTextBytes',
+        'forward.text': 'utf8_bytes<=messageTextBytes',
+        'send_to.messageOptions.messageId': 'utf8_bytes<=messageIdBytes',
+        'share_contact.messageId': 'utf8_bytes<=messageIdBytes',
+        'send_to.messageOptions.metadata': 'json_stringify_chars<=messageMetadataJsonChars',
+        'send_card.card': 'json_utf8_bytes<=cardEnvelopeBytes',
+        'request_card.card': 'json_utf8_bytes<=cardEnvelopeBytes',
+    },
+};