gif

## Overview GIF (Governed Intelligence Framework) is a governance runtime for AI tool invocation. Rather than logging what an agent did after the fact, it enforces policy before any tool executes, at the MCP (Model Context Protocol) layer. The project frames the problem as one of trajectories rather than records: a single agent can issue thousands of individually permissible queries across unrelated data sources in seconds, and the inference drawn from the aggregate may itself be a violation that record-level governance standards do not catch. ## What it does When an AI agent invokes a tool, GIF: 1. Checks the Persona — whether the governance identity is active, within its validity window, and permitted to call the tool. 2. Enforces scope — calls outside the Persona's declared scope are rejected and recorded as first-class governance events rather than ordinary errors. 3. Evaluates combination policies — adopter tool handlers call a GIF-provided evaluator before execution; if the set of data sources touched in the current session crosses a declared sensitivity threshold, the call completing that combination is blocked. The README's example: financial records, HR records, and communications metadata may each be permissible alone, but their join across separate calls may not be. 4. Records everything — permitted calls, rejections, and sessions, with INSERT-only permissions at the database level. ## Key concepts - **Persona**: a governance identity carrying a required, non-nullable declared purpose, explicit tool scope, temporal validity bounds, and a delegation chain. Created by human administrators before AI action. - **Scope**: an enumerated list of permitted actions; tools outside it cannot be called. - **Scope violation**: a first-class governance record, described as evidence the boundary worked. - **Combination policy**: a declared rule that a specific set of data sources accessed together in a session constitutes a boundary. GIF supplies the schema, an active-policy evaluator, and fail-closed semantics. The v0.1 evaluator uses first-match policy resolution; exhaustive evaluation is listed as a v0.2 trajectory item. - **Audit trail**: INSERT-only at the database permission level — the application role cannot UPDATE or DELETE audit records. - **Delegation chain**: child Personas hold strict subsets of parent scope, so sub-agent actions trace back to the root administrative authority. ## Architecture Two Docker containers: PostgreSQL 16 and a Node.js MCP server. Clients POST to the MCP server, which validates the Persona, enforces scope, and dispatches the tool; PostgreSQL holds personas, sessions, audit_events, and scope_violations. The combination-policy evaluator is exposed as a primitive that adopter tool servers invoke at their own dispatch points. The enforcement engine ships as an importable package (`gif-enforcement`), registered as a versioned git dependency, so adopters can add domain tools without modifying GIF source. ## Audit integrity Audit records are hash-chained at the database layer: a trigger computes a SHA-256 digest over a canonical byte form and links it to the previous row's digest, so after-the-fact mutation or deletion breaks the chain. A verifier CLI walks partitions, recomputes digests, and reports mismatches and chain breaks. The canonical form and verification procedure are specified in a separate Tamper-Evident Audit Record Contract repository (canonical form `audit-record-contract/1`, originally submitted to MCP as SEP-3004), for which GIF is the reference implementation. A mirrored vector set lives in the repository; the README states `npm run vectors` expects 26 vectors passing. ## Quick start Prerequisites are Docker Engine 24+, Docker Compose v2, and Git. The documented flow clones the `v0.2.4` tag, copies `.env.example` while stripping the placeholder secret, appends a generated `IDENTITY_HMAC_SECRET`, sets real passwords, and runs `docker compose up -d --build`. The database initializes roles, schema, and migrations automatically. The MCP server refuses to start if the HMAC secret remains the placeholder or is shorter than 32 bytes. Both published ports bind to `127.0.0.1` by default; `GIF_BIND_ADDR` widens this, and a production deployment runbook is referenced. The MCP endpoint validates the browser `Origin` header, answering 403 for disallowed origins unless listed in `GIF_ALLOWED_ORIGINS`; clients sending no Origin header are unaffected. Health is checked via `GET /health`. ## Current state The README recommends pinning `v0.2.4`, which runs on the MCP SDK 2.0 substrate and carries v0.2 governance-session semantics: explicit `gif_session_id` handles minted by `session_start`, caller-driven close, and wall-clock TTL. Core enforcement is described as complete and validated end-to-end against a real PostgreSQL 16 instance, with an integration suite and conformance scenarios run on every commit via CI, and TypeScript strict mode throughout. Shipped capabilities listed include persona lifecycle, the MCP enforcement layer with Streamable HTTP transport, the append-only hash-chained audit trail with a chain-verifier CLI, scope violation detection, delegation chain enforcement, session management, tool registry and registry-driven dispatch, enforcement packaging, the combination policy primitive, and provisioner identity binding via an HMAC identity token. A legacy `v0.1.0` release on the retired MCP SDK v1 substrate is no longer recommended: it lacks SQL-identifier hardening (advisory GHSA-47gp-w74f-grvr) and receives no backports. The README states the injection affects tags up to and including `v0.2.0-rc.1`, with `v0.2.0-rc.2` the first patched tag, and points existing adopters to a migration document. A compliance hardening roadmap covering external timestamping anchors, encryption at rest, multi-tenant operational hardening, and per-scope audit chains is documented in the product overview. ## Documentation and license The repository ships a plain-language guide, a product overview, a codebase walkthrough, architecture diagrams, a secrets document, contributor and adopter runbooks, and runnable conformance vectors. Licensed under Apache License 2.0; copyright 2026 Notboatanchor Labs LLC.