AI music generation via Cognitum Music (cogmusic MCP) — compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master through your own…

AI music generation via Cognitum Music — compose lyrics/prompts, generate tracks, separate stems, extract MIDI, and master, all through the cogmusic MCP server against your own Cognitum account.
Wraps the cogmusic MCP bridge as a Ruflo plugin with 2 agents, 7 skills, and one dispatcher command. Unlike most sibling plugins, there's no locally-executed CLI runtime here — every real generation runs on a remote GPU inference service (MiniMax-Music3), reached over a hand-rolled MCP server your own account authenticates against with a personal access token you mint yourself.
cogmcp_... personal access token, minted at music.cognitum.one/mcp (sign in → "Generate connection token"). Shown exactly once — copy it immediately. This plugin cannot mint or rotate this token for you.cogmusic@0.1.1 or later registered as an MCP server: ``bash claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest ` 0.1.0 has no fetch timeout override and fails any create_production call that runs past Node's ~5-minute default — real generations routinely take longer. See the music-connect` skill for the full setup flow.claude --plugin-dir plugins/ruflo-music
cogmusic exposes 6 tools once registered:
claude mcp add cogmusic --env COGMUSIC_TOKEN=cogmcp_... -- npx -y cogmusic@latest
claude mcp get cogmusic # expect: ✔ Connected
| Tool | Purpose |
|---|---|
list_productions | List saved productions (metadata + audio_url each) |
get_production | Fetch one production's current metadata + audio_url |
create_production | Generate a new track from lyrics + a style prompt (blocks for minutes) |
separate_stems | 4-stem separation (vocals/drums/bass/other) |
extract_midi | Pitch-tracked MIDI/score extraction |
master | LUFS loudness normalization + peak limiting |
| Agent | Role |
|---|---|
music-composer | Writes structured lyrics + a genre/style prompt from a creative brief. Calls no MCP tools. |
music-producer | Pipeline entry point — delegates composition to music-composer, calls create_production, caches the result, optionally post-processes, reports the audio_url. |
| Skill | Purpose |
|---|---|
music-connect | One-time setup — register the cogmusic MCP server |
music-generate | Generate a track from a fully-specified brief |
music-list | List all productions in the account |
music-get | Fetch one production's metadata + audio_url |
music-stems | Run 4-stem separation on an existing production |
music-midi | Extract MIDI from an existing production |
music-master | Run a mastering (LUFS) pass on an existing production |
/music connect [--token cogmcp_...]
/music generate <brief>
/music list
/music get <production-id>
/music stems <production-id>
/music midi <production-id>
/music master <production-id>
audio_url, not the audio itself — always a separate authenticated GET with the same cogmcp_ token as Authorization: Bearer.audio_url yet. separate_stems/extract_midi confirm what was produced (has_stems/has_midi via get_production), but the derived audio/MIDI files are dashboard-only today — the PAT-authorized-URL pattern that already covers the primary track (see Architecture Decisions) hasn't been extended to these two endpoints upstream.@claude-flow/cli v3.6 major+minor.cogmusic@0.1.1+ npm package (stdio↔HTTP MCP bridge) registered via claude mcp add; no local compute — generation runs on a remote GPU service you don't control.bash plugins/ruflo-music/scripts/smoke.sh is the contract.This plugin owns two AgentDB namespaces (kebab-case, follows the convention from ruflo-agentdb ADR-0001 §"Namespace convention"):
| Namespace | Purpose |
|---|---|
music-productions | Cached production metadata — id, title, audio_url, prompt, lyrics, duration, processing-step flags — for recall without a round-trip to list_productions/get_production |
music-briefs | The creative brief that produced each production, keyed by production id, so a later "make another one like that" can retrieve the exact prompt/lyrics shape that worked |
All access via memory_* (namespace-routed). No agentdb_pattern-* or agentdb_hierarchical-* calls with a namespace argument anywhere in this plugin. Reserved namespaces (pattern, claude-memories, default) are never shadowed.
bash plugins/ruflo-music/scripts/smoke.sh
# Expected: "10 passed, 0 failed"
audio_url delivery pattern, namespace claims, disclosed reliability posture.MIT
Function-hook mod (ADR-445 pattern, hooks/register.ts). It adds, with no network, no process spawning and no model call:
cogmusic call (create_production, separate_stems, master, extract_midi) or memory write whose prompt/lyrics/payload holds a secret (prompts leave the machine for music.cognitum.one). The deny reason names the rule, never the value./music-mod: local status and scan <text> (secret check, same rules as the guard); the status file also counts productions started..claude-flow/music-mod/status.json ({version:1, updatedMs, guard, checked, blocked, ...}), written at session start and when counters change.Per-prompt context is deliberately not added: this plugin has nothing worth attaching to every prompt.
| Option | Default | Effect |
|---|---|---|
guard | on | refuse the calls above |
Test: claude plugin validate plugins/ruflo-music, claude plugin test plugins/ruflo-music, bash plugins/ruflo-music/scripts/smoke.sh.
hooks/register.ts 61 lines1import type { Hook, Register } from 'claude-code'
2
3import { answer } from './command'
4import { verdict } from './guard'
5import { readOptions, type ModOptions } from './options'
6import { newStats, STATUS_PATH, statusText, type Stats } from './status'
7
8type Dollar = Parameters<Hook<'session.start'>>[0]
9
10/** Everything one session of the mod keeps: its settings, counters and the project root. */
11type Session = { readonly opts: ModOptions; readonly stats: Stats; root?: string }
12
13async function flush($: Dollar, s: Session): Promise<void> {
14 if (s.root === undefined) return
15 try {
16 await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, { guard: s.opts.guard }, await $.clock.now()))
17 } catch {
18 /* the status file is a courtesy */
19 }
20}
21
22/**
23 * ruflo-music as a mod (ADR-445 pattern): a tighten-only guard on this plugin's own tools, `/music-mod`, and a status file the console
24 * reads. No network, no process spawning, no model call: only tools already connected.
25 */
26export const register: Register = (on, options) => {
27 const s: Session = { opts: readOptions(options), stats: newStats() }
28
29 on('session.start', async ($, e, next) => {
30 const result = await next(e)
31 s.root = (await $.session.root()) as string | undefined
32 try {
33 await $.command.register({ name: 'music-mod', description: 'ruflo-music mod: status, scan <text>' })
34 } catch {
35 /* a name taken by another plugin must not stop the mod */
36 }
37 await flush($, s)
38 return result
39 })
40
41 if (s.opts.guard) {
42 on('tool.call', async ($, e, next) => {
43 const before = s.stats.checked
44 const reason = verdict(e.tool, e, s.opts, s.stats)
45 if (reason === undefined) {
46 if (s.stats.checked !== before) await flush($, s)
47 return next(e)
48 }
49 s.stats.blocked++
50 await flush($, s)
51 return { deny: reason }
52 })
53 }
54
55 /** `/music-mod` (the plugin's own command is a prompt command, which no hook can answer). */
56 on('command.run', { command: 'music-mod' }, async (_$, e) => {
57 const args = typeof e.args === 'string' ? e.args : ''
58 return { text: answer(args, s.opts, s.stats) }
59 })
60}
61hooks/command.ts 29 lines1import { secretsIn } from './screen'
2import type { ModOptions } from './options'
3import type { Stats } from './status'
4
5const HELP = ['/music-mod status', '/music-mod scan <text>'].join('\n')
6
7/** `/music-mod` is answered locally and takes no model turn. */
8export function answer(args: string, opts: ModOptions, stats: Stats): string {
9 const [verb = '', ...rest] = args.trim().split(/\s+/)
10 const arg = rest.join(' ')
11
12 if (verb === '' || verb === 'help') return HELP
13
14 if (verb === 'status') {
15 return [
16 `guard ${opts.guard ? 'on' : 'off'}`,
17 `checked ${stats.checked} · blocked ${stats.blocked} · productions started ${stats.productions}${stats.lastBlock ? ` · last: ${stats.lastBlock}` : ''}`,
18 ].join('\n')
19 }
20
21 if (verb === 'scan') {
22 if (arg === '') return 'usage: /music-mod scan <text>'
23 const found = secretsIn(arg)
24 return found.length ? `The guard would refuse a write or call carrying that (${found.join(', ')}).` : 'Nothing secret-shaped found: the guard would let that through.'
25 }
26
27 return `Unknown: ${verb}\n${HELP}`
28}
29hooks/guard.ts 48 lines1import { hasSecret, secretsIn, textsOf } from './screen'
2import type { ModOptions } from './options'
3import type { Stats } from './status'
4
5const WRITERS = new Set(['memory_store', 'agentdb_pattern-store', 'agentdb_hierarchical-store'])
6const OWN = new Set(['create_production', 'separate_stems', 'master', 'extract_midi'])
7
8const toolOf = (name: string) => (name.startsWith('mcp__') ? name.slice(name.lastIndexOf('__') + 2) : name)
9const serverOf = (name: string) => (name.startsWith('mcp__') ? name.slice(5, name.lastIndexOf('__')) : '')
10/** The cogmusic server, however the plugin names it (`cogmusic` or `plugin_ruflo-music_cogmusic`). */
11const isCogmusic = (name: string) => serverOf(name).includes('cogmusic') && OWN.has(toolOf(name))
12
13/** This plugin's namespaces. A `memory_store` outside them is another plugin's write: still screened, but its refusal must not claim it. */
14const OWN_NS = /^music/i
15const namespaceOf = (input: unknown): string | undefined => {
16 const top = typeof input === 'object' && input !== null ? (input as Record<string, unknown>) : {}
17 const inner = typeof top.input === 'object' && top.input !== null ? (top.input as Record<string, unknown>) : {}
18 return [top.namespace, inner.namespace].find((n): n is string => typeof n === 'string')
19}
20const foreignStore = (tool: string, input: unknown): boolean => /(?:^|__)memory_store$/.test(tool) && !OWN_NS.test(namespaceOf(input) ?? '')
21/** The refusal for a secret in another plugin's `memory_store`: what was found and which namespace, never an owner and never content. */
22function foreignRefusal(input: unknown): string {
23 const ns = namespaceOf(input)
24 const label = (ns ?? '').replace(/[^\w.:-]/g, '').slice(0, 40)
25 const where = !ns ? 'no namespace' : label && !hasSecret(ns) && !hasSecret(label) ? `namespace "${label}"` : 'a namespace not shown here'
26 return `ruflo-music: a secret-shaped value (a key, token or password) was found in a memory write; the call targeted ${where}. Store a reference to where it lives, not the value.`
27}
28
29/**
30 * The reason a call is refused, or undefined when it may go. Prompts and lyrics leave the machine for music.cognitum.one, and memory
31 * writes persist, so neither may carry a key, token or password. Names the rule, never echoes the value.
32 */
33export function verdict(tool: string, input: unknown, _opts: ModOptions, stats: Stats): string | undefined {
34 const sends = isCogmusic(tool)
35 if (!sends && !WRITERS.has(toolOf(tool))) return undefined
36 stats.checked++
37 const found = textsOf(input).flatMap(secretsIn)
38 if (found.length === 0) {
39 if (sends && toolOf(tool) === 'create_production') stats.productions++
40 return undefined
41 }
42 stats.lastBlock = found[0]
43 if (!sends && foreignStore(tool, input)) return foreignRefusal(input)
44 return sends
45 ? 'ruflo-music: this prompt or lyrics hold what looks like a secret (a key, token or password); they would be sent to the music service. Remove it and try again.'
46 : 'ruflo-music: this memory write holds what looks like a secret (a key, token or password). Store a reference to where it lives, not the value.'
47}
48hooks/options.ts 17 lines1import type { PluginOptions } from 'claude-code'
2
3/** The plugin's `userConfig`, validated: a bad value is the default (guard on). */
4export type ModOptions = {
5 readonly guard: boolean
6}
7
8// BEGIN SHARED FLAG (generated by scripts/sync-mod-screen.mjs; edit plugins/ruflo-agentdb/hooks/options.ts)
9export const flag = (value: unknown, fallback: boolean) =>
10 value === true || value === 'true' || value === 'on' ? true : value === false || value === 'false' || value === 'off' ? false : fallback
11// END SHARED FLAG
12
13export function readOptions(options: PluginOptions | undefined): ModOptions {
14 const o = options ?? {}
15 return { guard: flag(o.guard, true) }
16}
17hooks/status.ts 19 lines1/** Counters the mod keeps for the session and writes to `.claude-flow/music-mod/status.json` for the console. */
2export type Stats = {
3 checked: number
4 blocked: number
5 /** Productions started (create_production calls seen). */
6 productions: number
7 /** Why the last call was refused: a rule name, never the text that tripped it. */
8 lastBlock?: string
9}
10
11export const newStats = (): Stats => ({ checked: 0, blocked: 0, productions: 0 })
12
13export const STATUS_PATH = '.claude-flow/music-mod/status.json'
14
15/** The file's text; `version` lets the console refuse a shape it does not know. */
16export function statusText(stats: Stats, mode: Record<string, unknown>, nowMs: number): string {
17 return `${JSON.stringify({ version: 1, updatedMs: nowMs, ...mode, ...stats }, null, 2)}\n`
18}
19hooks/screen.ts 262 lines1/**
2 * Pure text screening for the ruflo-music mod (ADR-445 pattern). Findings are NAMES only: the matched text is never returned, logged or
3 * counted by value, so a deny reason cannot leak what it caught.
4 */
5
6// BEGIN SHARED SCREEN (generated from plugins/ruflo-agentdb/hooks/screen.ts by scripts/sync-mod-screen.mjs; do not edit in a copy)
7export type Rules = readonly (readonly [string, RegExp])[]
8
9/** The secret shapes every mod screens for. A plugin adds its own after these, outside the markers. */
10export const COMMON_SECRETS: Rules = [
11 ['private key', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
12 ['aws access key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
13 ['github token', /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,})\b/],
14 ['slack token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/],
15 ['slack webhook', /\bhooks\.slack\.com\/services\/T[A-Z0-9]{6,}\/B[A-Z0-9]{6,}\/[A-Za-z0-9]{16,}/],
16 ['google api key', /\bAIza[0-9A-Za-z_-]{35}\b/],
17 ['anthropic or openai key', /\bsk-(?:(?:ant|proj|svcacct|admin)-[A-Za-z0-9_-]{20,}|(?=[A-Za-z]{0,40}\d)[A-Za-z0-9]{32,})/],
18 ['stripe key', /\b[rs]k_live_[A-Za-z0-9]{16,}/],
19 ['npm token', /\bnpm_[A-Za-z0-9]{36}\b/],
20 ['huggingface token', /\bhf_[A-Za-z0-9]{30,}\b/],
21 ['sendgrid key', /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/],
22 ['twilio key', /\bSK[0-9a-f]{32}\b/],
23 ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/],
24 ['bearer token', /\bBearer\s+([A-Za-z0-9._~+/=-]{24,})/],
25 ['database url with credentials', /\b[a-z][a-z0-9+.-]{1,20}:\/\/[^\s:@/]+:[^\s@/]{3,}@[^\s/]+/i],
26]
27
28export const INJECTION: Rules = [
29 ['override instructions', /\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b(?:previous|prior|above|earlier|all|any|system)\b[^.\n]{0,30}\b(?:instructions?|rules?|prompts?|guidelines?)\b/i],
30 ['role reassignment', /\byou are (?:now|no longer)\b|\bact as (?:an? )?(?:unrestricted|jailbroken)\b/i],
31 ['new instructions', /\b(?:new|updated|real) (?:system )?instructions?\s*:/i],
32 ['fake role tags', /<\/?\s*(?:system|assistant|developer|instructions?)\s*>|^\s*(?:system|assistant)\s*:/im],
33 ['concealment', /\bdo not (?:tell|inform|mention|reveal)[^.\n]{0,30}\b(?:user|human|operator)\b/i],
34 ['exfiltration', /\b(?:exfiltrate|send|post|upload)\b[^.\n]{0,50}\b(?:secrets?|credentials?|tokens?|api keys?|\.env)\b/i],
35 ['shell pipe', /\b(?:curl|wget)\b[^|\n]{0,200}\|\s*(?:sudo\s+)?(?:ba|z)?sh\b/i],
36]
37
38// C0/C1 controls (keeping tab and newline), DEL, soft hyphen, combining grapheme joiner, Arabic letter mark, Hangul and Mongolian fillers/separators,
39// zero-width, bidi (overrides and isolates) and invisible-format characters, variation selectors; built with escapes, never raw.
40const INVISIBLE = new RegExp(
41 '[\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f\\u00ad\\u034f\\u061c\\u115f\\u1160\\u17b4\\u17b5\\u180b-\\u180e\\u200b-\\u200f\\u2028-\\u202e\\u2060-\\u206f\\u3164\\ufe00-\\ufe0f\\ufeff\\uffa0\\ufff9-\\ufffb]',
42 'g',
43)
44
45/** Longest input scanned in one pass; a longer one keeps its head and tail halves. One regex pass per rule, so cost stays linear. */
46const MAX_SCAN = 200_000
47
48/** Input bounded to MAX_SCAN characters with invisible characters removed, so none can hide a secret or a phrase. */
49export const bare = (text: string) =>
50 (text.length > MAX_SCAN ? text.slice(0, MAX_SCAN / 2) + '\n' + text.slice(-MAX_SCAN / 2) : text).replace(INVISIBLE, '')
51
52// A value is a secret CANDIDATE only when it is not a reference (env var, call, identifier path, placeholder, secret-manager path) and its
53// shape is random enough: at least two character classes, one of them a digit or symbol, and Shannon entropy of at least 2.5 bits per character.
54const PLACEHOLDER = /placeholder|your[-_ ]|example|changeme|change[-_]?me|redacted|dummy|replace[-_]?me|insert[-_]|\*{3,}|x{5,}|\.{3}|^(?:none|null|undefined|true|false)$/i
55const REFERENCE =
56 /^(?:\$(?:\{[^}]*\}|\(|[A-Za-z_]\w*$)|%[^%]*%$|<[^>]*>$|\{\{|process\.env|os\.environ|env[.[]|import\.meta|System\.getenv|secrets?\.|vault:|op:\/\/|ref\+|arn:|projects\/[^/]+\/secrets\/|gcp:|kms:|aws:|file:)/i
57const CALL = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\(|^[A-Za-z_$][\w$]*\[/
58const IDENT_PATH = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/
59const UUID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i
60const NAME_LIKE = /^[a-z][a-z0-9]*(?:[-_./][a-z0-9]+){2,}$/
61
62function entropy(v: string): number {
63 const counts = new Map<string, number>()
64 for (const ch of v) counts.set(ch, (counts.get(ch) ?? 0) + 1)
65 let h = 0
66 for (const n of counts.values()) h -= (n / v.length) * Math.log2(n / v.length)
67 return h
68}
69
70/** True when `v` is a name, call, path or placeholder rather than a literal credential. */
71function isReference(v: string): boolean {
72 if (PLACEHOLDER.test(v) || REFERENCE.test(v) || CALL.test(v) || IDENT_PATH.test(v) || URL_NO_CREDS.test(v)) return true
73 return NAME_LIKE.test(v) && v.replace(/\D/g, '').length / v.length < 0.15
74}
75
76export function plausibleSecret(v: string): boolean {
77 if (v.length < 8 || v.length > 256 || /\s/.test(v) || UUID.test(v) || isReference(v)) return false
78 const symbol = /[^A-Za-z0-9]/.test(v)
79 const digit = /\d/.test(v)
80 const classes = [/[a-z]/.test(v), /[A-Z]/.test(v), digit, symbol].filter(Boolean).length
81 return classes >= 2 && (digit || symbol) && entropy(v) >= 2.5
82}
83
84/** Under a secret-named key a literal this long is a secret even with one character class or a UUID shape, unless it is a clear reference. */
85const KEYED_MIN = 20
86const PLACEHOLDER_WORD = /(?:^|[^a-z])(?:your|placeholder|changeme|change[-_]?me|example|redacted|dummy|replace[-_]?me|insert)(?:[^a-z]|$)|\*{3,}|x{5,}|\.{3}|^(?:none|null|undefined|true|false)$/i
87const URL_NO_CREDS = /^[a-z][a-z0-9+.-]{1,20}:\/\/[^\s@]*$/i
88
89/** Three or more lowercase hyphen-separated words (no hex or digit-only run of 8+, few digits), such as my-k8s-secret-name-for-database. */
90function hyphenName(v: string): boolean {
91 const parts = v.split('-')
92 return parts.length >= 3 && parts.every(p => /^[a-z0-9]{2,}$/.test(p) && !/^[0-9a-f]{8,}$/.test(p)) && v.replace(/\D/g, '').length / v.length < 0.15
93}
94
95function keyedSecret(v: string): boolean {
96 if (v.length < KEYED_MIN || v.length > 256 || /\s/.test(v)) return false
97 return !(PLACEHOLDER_WORD.test(v) || REFERENCE.test(v) || CALL.test(v) || IDENT_PATH.test(v) || URL_NO_CREDS.test(v) || (!UUID.test(v) && hyphenName(v)))
98}
99
100const KEY_NAME = /(?:api[_-]?key|secret|token|passw(?:or)?d|passwd|pwd|credential|private[_-]?key|auth(?!or))s?[A-Za-z0-9_-]{0,40}["']?\s*[:=]\s*/gi
101const QUOTED = /(["'\x60])((?:(?!\1)[^\n]){1,256})\1/y
102const BARE_VALUE = /[^\s"'\x60,;]{1,256}/y
103const QUERY_VALUE = /[^\s"'\x60,;&]{1,256}/y
104
105/** A secret-named key assigned a literal value: env style, JSON, YAML, code. Values that are calls, references or placeholders do not count. */
106function assignmentSecret(text: string): boolean {
107 let valueEnd = 0
108 for (const m of text.matchAll(KEY_NAME)) {
109 if (m.index < valueEnd) continue // a key-looking word inside the previous value, such as secretsmanager in an ARN
110 const at = m.index + m[0].length
111 let back = m.index
112 while (back > 0 && m.index - back < 64 && /[A-Za-z0-9_.-]/.test(text.charAt(back - 1))) back--
113 const re = /["'\x60]/.test(text.charAt(at)) ? QUOTED : /[?&]/.test(text.charAt(back - 1)) ? QUERY_VALUE : BARE_VALUE
114 re.lastIndex = at
115 const hit = re.exec(text)
116 const v = hit && (hit[2] ?? hit[0])
117 valueEnd = hit ? at + hit[0].length : at
118 if (v && (plausibleSecret(v) || keyedSecret(v))) return true
119 }
120 return false
121}
122
123/** A password in a URL's userinfo that is not a placeholder such as user:password or ${DB_PASSWORD}. */
124function urlCredential(url: string): boolean {
125 const pass = /^[^:]+:\/\/[^\s:@/]+:([^\s@/]+)@/.exec(url)?.[1]
126 if (!pass || /\$\{|\{\{|%\(|%s/.test(pass)) return false
127 return !/^(?:password|passwd|pass|pwd|secret|changeme|dbpassword|db_password|\$\w*|<.*>|\{.*\}|\*+|x+)$/i.test(pass) && !PLACEHOLDER.test(pass)
128}
129
130const CHECKS: Readonly<Record<string, (m: RegExpMatchArray) => boolean>> = {
131 'bearer token': m => !isReference(m[1] ?? ''),
132 'database url with credentials': m => urlCredential(m[0]),
133 'database url with password': m => urlCredential(m[0]),
134}
135const globals = new WeakMap<RegExp, RegExp>()
136
137function matches(name: string, re: RegExp, text: string): boolean {
138 if (name === 'key assignment') return assignmentSecret(text)
139 const check = CHECKS[name]
140 if (!check) return re.test(text)
141 let g = globals.get(re)
142 if (!g) globals.set(re, (g = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g')))
143 for (const m of text.matchAll(g)) if (check(m)) return true
144 return false
145}
146
147/**
148 * The text textsOf appends when it had to drop input (a node, character or per-string budget ran out). It is never matched against a rule:
149 * `names` reports it as a finding of its own, so every guard that asks "is there a secret in these texts" refuses what it could not read in full.
150 */
151export const TRUNCATED = 'ruflo-screen: input exceeded the screening budget'
152export const TRUNCATED_NAME = 'input too large to screen'
153
154/** Names of the rules that match `text` (already bare'd). A rule named 'key assignment' is judged by assignmentSecret, whatever its regex. */
155export const names = (rules: Rules, text: string) => text === TRUNCATED ? [TRUNCATED_NAME] : rules.filter(([name, re]) => matches(name, re, text)).map(([name]) => name)
156
157export type Findings = { readonly secrets: readonly string[]; readonly injection: readonly string[] }
158
159/** Names of every secret shape in `secrets` and every injection phrase found in `text`. Cost is linear in the capped input. */
160export function screenWith(secrets: Rules, text: string): Findings {
161 const bounded = bare(text)
162 return { secrets: names(secrets, bounded), injection: names(INJECTION, bounded) }
163}
164
165export const hasSecretIn = (secrets: Rules, text: string) => names(secrets, bare(text)).length > 0
166
167/** Makes stored text safe to show: no control or bidi characters, whitespace collapsed, at most `max` characters. */
168export function tidy(text: string, max: number): string {
169 const flat = text.replace(INVISIBLE, '').replace(/\s+/g, ' ').trim()
170 return flat.length > max ? `${flat.slice(0, Math.max(0, max - 1))}…` : flat
171}
172/** Bounds for textsOf: nodes visited, characters returned, the longest string read in full, the size of one returned chunk, chunk overlap. */
173export type TextLimits = { readonly nodes?: number; readonly chars?: number; readonly perString?: number }
174const NODES = 20_000
175const CHARS = 2_000_000
176const PER_STRING = 1_500_000
177const OVERLAP = 2_048
178const BARE_KEY_MIN = 8
179
180/** A string as texts the screen can read whole: one text up to MAX_SCAN, else overlapping MAX_SCAN windows so a secret anywhere is inside one. */
181function windows(text: string, out: string[]): void {
182 if (text.length <= MAX_SCAN) {
183 out.push(text)
184 return
185 }
186 for (let at = 0; ; at += MAX_SCAN - OVERLAP) {
187 out.push(text.slice(at, at + MAX_SCAN))
188 if (at + MAX_SCAN >= text.length) return
189 }
190}
191
192/**
193 * Every string in a tool input, for the screen to read: iterative (no recursion, so nesting 5000 deep cannot overflow the stack) and
194 * breadth-first (siblings before depth, so a long list cannot hide a nested value). A string under an object key comes back as `key=value`,
195 * so a secret-named key is judged with its value; a key whose value is not a string is returned bare. Strings longer than the screen window
196 * come back as overlapping windows; one over `perString` keeps its head and tail. Work is bounded by `nodes` slots and `chars` characters.
197 * Anything dropped (slots or characters ran out, or a string lost its middle) is reported by a final TRUNCATED text, which `names` and
198 * `hasSecretIn` count as a finding, so the screen fails closed instead of passing what it did not read.
199 */
200export function textsOf(input: unknown, limits: TextLimits = {}): string[] {
201 const out: string[] = []
202 let slots = limits.nodes ?? NODES
203 let chars = limits.chars ?? CHARS
204 const perString = limits.perString ?? PER_STRING
205 let truncated = false
206 const take = (text: string): void => {
207 if (chars <= 0) {
208 truncated = true
209 return
210 }
211 if (text.length <= Math.min(perString, chars)) {
212 chars -= text.length
213 windows(text, out)
214 return
215 }
216 truncated = true
217 const half = Math.floor(Math.min(perString, chars) / 2)
218 chars -= 2 * half
219 windows(text.slice(0, half), out)
220 windows(text.slice(-half), out)
221 }
222 const queue: unknown[] = [input]
223 let head = 0
224 for (; head < queue.length && chars > 0; head++) {
225 const node = queue[head]
226 if (typeof node === 'string') take(node)
227 else if (Array.isArray(node)) {
228 let i = 0
229 for (; i < node.length && slots > 0; i++, slots--) if (i in node) queue.push(node[i])
230 if (i < node.length) truncated = true
231 } else if (typeof node === 'object' && node !== null) {
232 for (const k in node) {
233 if (slots-- <= 0) {
234 truncated = true
235 break
236 }
237 if (!Object.prototype.hasOwnProperty.call(node, k)) continue
238 const v = (node as Record<string, unknown>)[k]
239 if (typeof v === 'string') queue.push(k + '=' + v)
240 else {
241 if (k.length >= BARE_KEY_MIN) take(k)
242 queue.push(v)
243 }
244 }
245 }
246 }
247 if (queue.length > head) truncated = true
248 if (truncated) out.push(TRUNCATED)
249 return out
250}
251// END SHARED SCREEN
252
253const SECRETS: Rules = [
254 ...COMMON_SECRETS,
255 ['key assignment', /\b[A-Za-z0-9_-]*(?:api[_-]?key|secret|token|passw(?:or)?d|credential)s?["']?\s*[:=]\s*["']?[A-Za-z0-9/+=_.-]{16,}/i],
256]
257
258/** Names of every secret shape found in `text`. Cost is linear in the capped input. */
259export const secretsIn = (text: string): string[] => names(SECRETS, bare(text))
260
261export const hasSecret = (text: string) => hasSecretIn(SECRETS, text)
262