Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.6 KB
Raw Blame
/**
 * src/core/source-id.ts — single canonical source_id validation.
 *
 * Dependency-free by design (no imports beyond TS stdlib). Imported by both
 * engines, cycle, source-resolver, sources-ops, and any future site that
 * needs to validate a source_id. Pre-v0.38 the regex was duplicated across
 * three files (`utils.ts` had a permissive variant; `sources-ops.ts` and
 * `source-resolver.ts` had the strict variant). Codex outside-voice flagged
 * the drift; this module is the consolidation.
 *
 * **Canonical regex (strict):** `^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$`
 *
 * Rules enforced:
 *   - 1-32 characters
 *   - lowercase alphanumeric only (no underscores, no dots, no slashes)
 *   - interior hyphens allowed
 *   - first and last character must be alphanumeric (no edge hyphens)
 *
 * Single-character source IDs like `a` or `1` are valid. Underscored ids
 * like `my_source` are rejected even though they passed the legacy
 * permissive regex — `sources-ops` always rejected them at creation time,
 * so no existing source IDs break.
 *
 * **Exports two validators:**
 *   - `isValidSourceId(s)`: boolean — for tiers that silently fall back
 *     to the next resolution step on invalid input (dotfile, brain_default).
 *   - `assertValidSourceId(s)`: void, throws — for tiers that must reject
 *     invalid input loudly (explicit `--source` flag, `GBRAIN_SOURCE` env,
 *     `cycleLockIdFor` primitive defense-in-depth).
 *
 * Codex P1-F flagged the need for both shapes.
 */

export const SOURCE_ID_RE = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;

/**
 * Sentinel meaning "span every source" (#1712). Deliberately NOT a valid
 * source id (underscores are rejected by SOURCE_ID_RE), so it can never
 * collide with a real source, be created via `sources add`, or leak into
 * lock ids / path joins. The resolver's explicit/env tiers pass it through
 * verbatim; `sourceScopeOpts` translates it to an unscoped read for trusted
 * local callers and keeps it as an unsatisfiable literal for remote callers
 * (fail-closed).
 */
export const ALL_SOURCES = '__all__';

/**
 * Sentinel for a legacy token whose stored source grant is an explicit empty
 * list (`gbrain auth rescope-token <name> --sources none`). Like
 * `ALL_SOURCES` it can never name a real source; `sourceScopeOpts`, the
 * dispatch fence and write submission refuse it instead of falling back to
 * the `default` floor.
 */
export const NO_SOURCES = '__none__';

/** Returns true if the string matches the canonical source_id regex. */
export function isValidSourceId(s: unknown): s is string {
  return typeof s === 'string' && SOURCE_ID_RE.test(s);
}

/**
 * Throws if the input doesn't match the canonical source_id regex.
 * Error message includes the offending value (JSON-stringified for
 * non-string types so debugging weird input is fast).
 */
export function assertValidSourceId(s: unknown): asserts s is string {
  if (!isValidSourceId(s)) {
    throw new Error(
      `Invalid source_id: ${JSON.stringify(s)}. ` +
      `Must be 1-32 lowercase alnum chars with optional interior hyphens ` +
      `(matches ${SOURCE_ID_RE}).`,
    );
  }
}

/**
 * Normalize the optional `source` field of an `/admin/api/register-client`
 * request body into a write source_id.
 *
 * Mirrors the CLI's `--source` flag. Returns the literal `'default'` when the
 * field is omitted (`undefined`/`null`) so every caller that doesn't send
 * `source` keeps landing on source_id='default' (the pre-source HTTP
 * register-client behavior). A present-but-invalid value throws (via
 * `assertValidSourceId`) so the route can surface a structured 400 instead of
 * failing at INSERT time.
 */
export function normalizeSourceInput(raw: unknown): string {
  if (raw === undefined || raw === null) return 'default';
  assertValidSourceId(raw);
  return raw;
}

/**
 * Normalize the optional `federatedRead` field of an
 * `/admin/api/register-client` request body into a source_id array, or
 * `undefined` when omitted.
 *
 * Mirrors the CLI's `--federated-read` flag. `undefined`/`null` → `undefined`
 * so `registerClientManual` applies its own default (`[sourceId]`, a
 * non-federated client whose read scope equals its write scope). A present
 * value must be a non-empty array whose every element is a valid source_id;
 * anything else throws for a structured 400.
 */
export function normalizeFederatedReadInput(raw: unknown): string[] | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (!Array.isArray(raw) || raw.length === 0) {
    throw new Error(
      `Invalid federatedRead: ${JSON.stringify(raw)}. ` +
      `Must be a non-empty array of source_ids.`,
    );
  }
  for (const s of raw) assertValidSourceId(s);
  return raw as string[];
}