Spec 0.1 — Public Draft

The auth.md Spec

An open convention for AI agent governance as files: readable by people, validated and enforced by machines, signed like a release.

The agent ecosystem standardized on plain-text convention files — agents.md for instructions, llms.txt for guidance, SKILL.md for skills, MCP for tools. There was no agreed file for governance: who an agent may act as, what it may do, what must be recorded, and when it must stop and ask a human. The auth.md convention fills that gap.

Canonical spec: the specification, JSON Schemas, and conformance fixtures live at github.com/H2OmAI/authmd — CC BY 4.0 text, Apache-2.0 schemas. Issues and PRs are open to everyone.

The files

A .gaas/ directory at the governed project's root:

FileDeclares
auth.mdWho or what may act: agent identities, trust tiers, delegation limits, and the actions that always require a human's yes
policy.mdThe rules: scope, severity, verdict, and declarative conditions
audit.mdRecord expectations: retention, signing mode, export cadence — validated against reality, drift surfaced
escalation.mdEscalation routes: approvers, timeouts, and what happens when nobody answers (never auto-approve)
attestation.sigA detached ES256 signature over the bundle — portable, offline-verifiable proof of the rules in force

Each .md file is YAML frontmatter (the machine contract, schema-validated) plus a Markdown body (the human rationale — hashed into the signature, never machine-interpreted). Governance you can diff in a pull request.

Conditions are declarative, never code

A governance file that can execute code is a supply-chain attack surface. Conditions in this convention are a structured matcher tree — portable across runtimes, reviewable by non-programmers, and safe to accept from any repo: 

policies:
  - id: no-bulk-customer-export
    description: Block bulk exports of customer records
    severity: mandatory
    verdict: block
    when:
      all:
        - { field: action.target.identifier, op: contains, value: customer }
        - { field: action.payload.estimated_impact.audience_size, op: gte, value: 1000 }

Validate in CI, today

The reference validator is open-source Python — local-only, no API key, no network: 

pip install gaas-spec

gaas validate          # validate ./.gaas — exits non-zero with findings
gaas sign --key org-key.pem --key-id acme-2026
gaas verify --pub acme-2026=org-pub.pem

An implementation conforms to spec 0.1 when it accepts every bundle in the spec repo's fixtures/valid/ and rejects every bundle in fixtures/invalid/ for the documented reason. Fixtures are ground truth: where prose and fixtures disagree, fixtures win.

GaaS is the reference runtime

GaaS validates these files, compiles them into enforced runtime policy scoped to your organization, countersigns applied bundles, and records the applied bundle's hash in the tamper-evident audit chain — binding what the rules said to what decisions were made. The audit record beneath it is free forever.

Status: spec 0.1 is a public draft. Runtime enforcement of governance files (validate/apply endpoints) is landing in the current release cycle; the spec, schemas, fixtures, and the gaas-spec validator are available now.

Related Pages