GOCC (Trust Layer)

Governance Operations Control Center - Policy gates, PII controls, audit logging, and metering.

Installation

pnpm add @aicr/gocc-client

Overview

GOCC is the central Trust Layer for all AICR services. It provides:

Policy Evaluation - Check permissions before actions
PII Detection & Redaction - Protect sensitive data
Audit Logging (Spine) - Immutable event trail
Usage Metering - Track and bill resource usage
Model Routing - AI provider selection and load balancing

Quick Start

import { createGOCCClient } from '@aicr/gocc-client';
 
const gocc = createGOCCClient({
  baseUrl: '/api/gocc',
  tenantId: 'tenant-123'
});
 
// Check policy before action
const allowed = await gocc.evaluatePolicy({
  action: 'document.export',
  resource: documentId,
  actor: userId
});
 
if (allowed.permit) {
  // Redact PII before export
  const safe = await gocc.redactPII(documentContent);
 
  // Record to audit trail
  await gocc.recordToSpine({
    action: 'document.exported',
    resourceId: documentId,
    actor: userId
  });
}

API Reference

`createGOCCClient(config)`

Create a GOCC client.

interface GOCCConfig {
  baseUrl: string;         // e.g., '/api/gocc' or 'https://...'
  tenantId?: string;       // Default tenant
  apiKey?: string;         // API authentication
  timeout?: number;        // Request timeout (ms)
}

Policy Evaluation

`gocc.evaluatePolicy(request)`

Check if an action is permitted.

interface PolicyRequest {
  action: string;          // e.g., 'document.read', 'document.update'
  resource: string;        // Resource ID
  resourceType?: string;   // e.g., 'document', 'plan'
  actor: string;           // User or service ID
  context?: Record<string, unknown>;  // Additional context
}
 
interface PolicyResult {
  permit: boolean;
  reason?: string;
  policies?: string[];     // Matching policy IDs
  obligations?: Obligation[];  // Required actions
}

Example:

const result = await gocc.evaluatePolicy({
  action: 'plan.delete',
  resource: 'plan-123',
  actor: 'user-456',
  context: { department: 'sales' }
});
 
if (!result.permit) {
  throw new Error(`Action denied: ${result.reason}`);
}

PII Controls

`gocc.detectPII(content)`

Detect PII in content.

const pii = await gocc.detectPII(documentText);
 
console.log(pii.found);  // true/false
console.log(pii.entities);  // [{ type: 'SSN', start: 10, end: 21 }, ...]

`gocc.redactPII(content, options)`

Redact PII from content.

const redacted = await gocc.redactPII(documentText, {
  types: ['SSN', 'EMAIL', 'PHONE', 'ADDRESS'],
  replacement: '[REDACTED]',  // or 'mask' for partial masking
  preserveFormat: true
});
 
console.log(redacted.content);  // Text with PII replaced
console.log(redacted.redactions);  // List of redactions made

Audit Trail (Spine)

`gocc.recordToSpine(event)`

Record an event to the immutable audit trail.

interface SpineEvent {
  action: string;
  resourceId?: string;
  resourceType?: string;
  actor: string;
  actorType?: 'user' | 'system' | 'api';
  details?: Record<string, unknown>;
  severity?: 'info' | 'warning' | 'critical';
}
 
await gocc.recordToSpine({
  action: 'document.analyzed',
  resourceId: 'doc-123',
  actor: 'user-456',
  details: {
    templateId: 'gap-analysis',
    findings: 5
  }
});

`gocc.querySpine(query)`

Query the audit trail.

const events = await gocc.querySpine({
  resourceId: 'doc-123',
  actions: ['document.analyzed', 'document.exported'],
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 100
});

Usage Metering

`gocc.recordUsage(usage)`

Record usage for billing.

await gocc.recordUsage({
  metric: 'ai.tokens',
  value: 1500,
  resourceId: 'analysis-123',
  metadata: { model: 'gpt-4' }
});

`gocc.getUsageSummary(query)`

Get usage summary.

const usage = await gocc.getUsageSummary({
  metric: 'ai.tokens',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'day'
});

HTTP API

`POST /api/gocc/policies/evaluate`

curl -X POST /api/gocc/policies/evaluate \
  -d '{"action": "document.export", "resource": "doc-123", "actor": "user-456"}'

`POST /api/gocc/pii/redact`

curl -X POST /api/gocc/pii/redact \
  -d '{"content": "Call me at 555-1234", "types": ["PHONE"]}'

`POST /api/gocc/spine/record`

curl -X POST /api/gocc/spine/record \
  -d '{"action": "document.exported", "resourceId": "doc-123", "actor": "user-456"}'

Service Integration

All Universal Services should integrate with GOCC:

import { createDAClient } from '@aicr/da-core';
import { createGOCCClient } from '@aicr/gocc-client';
 
const gocc = createGOCCClient({ baseUrl: '/api/gocc' });
const da = createDAClient({ goccClient: gocc });
 
// DA automatically:
// 1. Checks policies before analysis
// 2. Redacts PII in outputs
// 3. Records to Spine audit trail
// 4. Records usage metrics

Policy Types

Type	Example Actions
Resource	`document.read`, `document.update`, `document.delete`
Admin	`user.create`, `tenant.configure`, `policy.update`
Export	`document.export`, `report.download`, `data.export`
AI	`ai.analyze`, `ai.generate`, `ai.embed`

Oversight Service Overview