Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.2 KB
Raw Blame
/**
 * Raw Data operation cluster — pure move from operations.ts (v0.46.x
 * tranche 2). Op consts stay module-private; `rawDataOperations` below lists
 * them in EXACTLY the order they appear in the canonical `operations` array
 * in ../operations.ts. Never import from '../operations.ts' here (cycle).
 */

import type { Operation } from './contract.ts';
import { readPolicyOpts, requireWritablePage } from './context.ts';
import { enforceClientSlugFence } from './context.ts';
import { refuseGuestSourceWrite } from '../guests/admission.ts';
import { requestPrincipalForContext } from '../persistence/page-mutations.ts';

// --- Raw Data ---

const put_raw_data: Operation = {
  name: 'put_raw_data',
  idempotent: false,
  outputRedaction: 'no_stored_text',
  description: 'Store a raw provider payload (API response JSON) alongside a page, keyed by source. Use when keeping the original data an enrichment came from. Needs write scope. On page_not_found: create or resolve the page first.',
  params: {
    slug: { type: 'string', required: true, description: 'Slug of the page to attach the raw data to.' },
    source: { type: 'string', required: true, description: 'Data source (e.g., crustdata, happenstance)' },
    data: { type: 'object', required: true, description: 'Raw data object' },
  },
  mutating: true,
  scope: 'write',
  handler: async (ctx, p) => {
    enforceClientSlugFence(ctx, p.slug as string, 'put_raw_data');
    if (ctx.dryRun) return { dry_run: true, action: 'put_raw_data', slug: p.slug, source: p.source };
    // v0.31.8 (D7 + D21): thread ctx.sourceId.
    const sourceOpts = ctx.sourceId ? { sourceId: ctx.sourceId } : {};
    // GBRA-218: a remote caller's missing and member-hidden targets get the same page_not_found (no existence oracle).
    if (ctx.remote !== false) await requireWritablePage(ctx, p.slug as string, 'put_raw_data', 'page');
    await refuseGuestSourceWrite(ctx.engine, ctx.sourceId || 'default', () => requestPrincipalForContext(ctx), 'put_raw_data');
    await ctx.engine.putRawData(p.slug as string, p.source as string, p.data as object, sourceOpts);
    return { status: 'ok' };
  },
};

const get_raw_data: Operation = {
  name: 'get_raw_data',
  mutating: false,
  idempotent: true,
  outputRedaction: { exempt: 'explicit raw sidecar read by slug; governed by page visibility (CEO-17 raw-read exception)' },
  description: 'Retrieve raw data for a page. Raw data follows the page\'s soft-delete: a tombstoned (soft-deleted) page returns [] exactly like a missing page; restore_page brings the rows back, and get_page include_deleted: true verifies the tombstone.',
  params: {
    slug: { type: 'string', required: true, description: 'Slug of the page whose raw data to fetch.' },
    source: { type: 'string', description: 'Filter by source' },
  },
  handler: async (ctx, p) => {
    const scope = await readPolicyOpts(ctx);
    // #4352 remediation: a `visibility: private` page's raw data reads
    // exactly like a missing page's ([]) for untrusted callers — no
    // existence oracle.
    return ctx.engine.getRawData(p.slug as string, p.source as string | undefined, scope);
  },
  scope: 'read',
};


// Ops in EXACTLY the canonical `operations` array order.
export const rawDataOperations: Operation[] = [put_raw_data, get_raw_data];