gaas-spec 0.1.0__tar.gz

gaas_spec-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+nul
+
+# Claude Code (keep shared configs, ignore local/transient)
+.claude/settings.local.json
+.claude/history/
+.claude/plans/
+.claude/projects/
+.claude/todos/
+
+# Node / TypeScript
+node_modules/
+.vite/
+
+# Project
+*.log
+
+# Generated reports
+gaas-cost-audit.html
+
+# Super admin credentials (contains passwords)
+SUPER_ADMIN_CREDENTIALS.txt
+
+# Local development scripts (not part of tracked codebase)
+scripts/test-*.py
+scripts/diagnose-*.py
+scripts/send-*.py
+scripts/trigger-*.py
+scripts/uat-*.py
+test_results_*.json
+tests/e2e/
+
+# Local trash can (never committed)
+gaascan/
+
+# Local planning docs (never committed)
+.planning/
+
+# Confidential business & sales documents
+docs/business/
+docs/sales/
+
+# Session artifacts (Claude Code working docs)
+/DAY_*.md
+/DAYS_*.md
+/HANDOFF_*.md
+/think_tank.md
+
+# Auto-generated test reports
+apps/dashboard/playwright-report/
+apps/dashboard/test-results/
+apps/dashboard/e2e/screenshots/

gaas_spec-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: gaas-spec
+Version: 0.1.0
+Summary: Reference validator, signer, and verifier for the auth.md governance file convention (spec 0.1)
+Project-URL: Homepage, https://github.com/H2OmAI/authmd
+Project-URL: Specification, https://github.com/H2OmAI/authmd
+Project-URL: Repository, https://github.com/H2OmAI/gaas
+Author-email: H2Om <sdk@gaas.is>
+License-Expression: Apache-2.0
+Keywords: agents,ai,auth.md,gaas,governance,policy-as-code
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: jsonschema>=4.21.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gaas-spec
+
+Reference validator, signer, and verifier for the **auth.md governance file convention** — spec 0.1.
+
+The convention: a `.gaas/` directory (`auth.md`, `policy.md`, `audit.md`, `escalation.md`, `attestation.sig`) declaring how an AI agent is governed — readable by people, validated and enforced by machines, signed like a release. Spec, schemas, and conformance fixtures: **[github.com/H2OmAI/authmd](https://github.com/H2OmAI/authmd)**.
+
+Local-only: no network, no API key. Suitable for CI.
+
+## Install
+
+```bash
+pip install gaas-spec
+```
+
+## CLI
+
+```bash
+gaas validate            # validate ./.gaas (or: gaas validate path/to/repo)
+gaas sign --key org-key.pem --key-id acme-2026
+gaas verify --pub acme-2026=org-pub.pem
+```
+
+`validate` exits non-zero with findings when the bundle doesn't conform — wire it straight into CI. `sign` refuses non-conforming bundles. `verify` checks every file hash against the attestation manifest before checking signatures, so a tampered bundle fails loudly.
+
+## Library
+
+```python
+from gaas_spec import parse_bundle, validate, sign, verify
+
+bundle = parse_bundle(".")           # finds ./.gaas
+findings = validate(bundle)          # [] means conforming
+attestation = sign(bundle, private_key_pem, key_id="acme-2026", signer="org")
+results = verify(bundle, attestation, {"acme-2026": public_key_pem})
+```
+
+## Conformance
+
+This package vendors the spec repo's fixtures and runs them in its test suite — it is the reference implementation and must agree with the fixtures at all times. Signing is ES256 (ECDSA P-256 + SHA-256) over an RFC 8785 canonical-JSON manifest hash, per SPEC-attestation.md.
+
+## License
+
+Apache-2.0. The spec text itself is CC BY 4.0 at the spec repo.

gaas_spec-0.1.0/README.md

@@ -0,0 +1,42 @@
+# gaas-spec
+
+Reference validator, signer, and verifier for the **auth.md governance file convention** — spec 0.1.
+
+The convention: a `.gaas/` directory (`auth.md`, `policy.md`, `audit.md`, `escalation.md`, `attestation.sig`) declaring how an AI agent is governed — readable by people, validated and enforced by machines, signed like a release. Spec, schemas, and conformance fixtures: **[github.com/H2OmAI/authmd](https://github.com/H2OmAI/authmd)**.
+
+Local-only: no network, no API key. Suitable for CI.
+
+## Install
+
+```bash
+pip install gaas-spec
+```
+
+## CLI
+
+```bash
+gaas validate            # validate ./.gaas (or: gaas validate path/to/repo)
+gaas sign --key org-key.pem --key-id acme-2026
+gaas verify --pub acme-2026=org-pub.pem
+```
+
+`validate` exits non-zero with findings when the bundle doesn't conform — wire it straight into CI. `sign` refuses non-conforming bundles. `verify` checks every file hash against the attestation manifest before checking signatures, so a tampered bundle fails loudly.
+
+## Library
+
+```python
+from gaas_spec import parse_bundle, validate, sign, verify
+
+bundle = parse_bundle(".")           # finds ./.gaas
+findings = validate(bundle)          # [] means conforming
+attestation = sign(bundle, private_key_pem, key_id="acme-2026", signer="org")
+results = verify(bundle, attestation, {"acme-2026": public_key_pem})
+```
+
+## Conformance
+
+This package vendors the spec repo's fixtures and runs them in its test suite — it is the reference implementation and must agree with the fixtures at all times. Signing is ES256 (ECDSA P-256 + SHA-256) over an RFC 8785 canonical-JSON manifest hash, per SPEC-attestation.md.
+
+## License
+
+Apache-2.0. The spec text itself is CC BY 4.0 at the spec repo.

gaas_spec-0.1.0/gaas_spec/__init__.py

@@ -0,0 +1,30 @@
+"""gaas-spec — reference validator/signer/verifier for the auth.md convention.
+
+Spec: https://github.com/H2OmAI/authmd (version 0.1)
+"""
+
+from .bundle import (
+    BUNDLE_FILES,
+    SPEC_VERSIONS,
+    Finding,
+    GovernanceBundle,
+    parse_bundle,
+    validate,
+)
+from .signing import canonical_manifest, manifest_hash, sign, verify
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BUNDLE_FILES",
+    "SPEC_VERSIONS",
+    "Finding",
+    "GovernanceBundle",
+    "parse_bundle",
+    "validate",
+    "canonical_manifest",
+    "manifest_hash",
+    "sign",
+    "verify",
+    "__version__",
+]

gaas_spec-0.1.0/gaas_spec/bundle.py

@@ -0,0 +1,220 @@
+"""Parse and validate .gaas/ governance bundles (spec 0.1).
+
+The validator is deliberately strict: schema validation plus the semantic
+checks the spec requires beyond JSON Schema (default escalation route,
+timeout-chain termination, matcher depth/leaf limits, spec version).
+Fixtures in the spec repo are ground truth.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from jsonschema import Draft202012Validator
+
+SPEC_VERSIONS = ("0.1",)
+BUNDLE_FILES = ("auth.md", "policy.md", "audit.md", "escalation.md")
+MAX_MATCHER_DEPTH = 8
+MAX_MATCHER_LEAVES = 64
+
+_SCHEMAS: dict[str, Draft202012Validator] = {}
+
+
+def _schema(fname: str) -> Draft202012Validator:
+    if fname not in _SCHEMAS:
+        ref = resources.files("gaas_spec.schemas") / f"{fname.removesuffix('.md')}.schema.json"
+        _SCHEMAS[fname] = Draft202012Validator(json.loads(ref.read_text()))
+    return _SCHEMAS[fname]
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single validation finding."""
+
+    file: str
+    code: str
+    message: str
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return f"{self.file}: [{self.code}] {self.message}"
+
+
+@dataclass
+class GovernanceBundle:
+    """A parsed .gaas/ bundle: raw bytes, frontmatter, and file hashes."""
+
+    root: Path
+    files: dict[str, bytes] = field(default_factory=dict)
+    frontmatter: dict[str, dict] = field(default_factory=dict)
+    parse_findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def hashes(self) -> dict[str, str]:
+        return {
+            name: f"sha256:{hashlib.sha256(raw).hexdigest()}"
+            for name, raw in sorted(self.files.items())
+        }
+
+
+def parse_bundle(path: str | Path) -> GovernanceBundle:
+    """Parse a bundle directory (either the .gaas/ dir or its parent)."""
+    root = Path(path)
+    if (root / ".gaas").is_dir():
+        root = root / ".gaas"
+    bundle = GovernanceBundle(root=root)
+    if not root.is_dir():
+        bundle.parse_findings.append(
+            Finding("<bundle>", "bundle-not-found", f"no such directory: {root}")
+        )
+        return bundle
+
+    for name in BUNDLE_FILES:
+        f = root / name
+        if not f.is_file():
+            continue
+        raw = f.read_bytes()
+        bundle.files[name] = raw
+        text = raw.decode("utf-8", errors="strict")
+        if not text.startswith("---\n") or "\n---" not in text[4:]:
+            bundle.parse_findings.append(
+                Finding(name, "missing-frontmatter", "file must start with a YAML frontmatter block")
+            )
+            continue
+        end = text.index("\n---", 4)
+        try:
+            fm = yaml.safe_load(text[4:end])
+        except yaml.YAMLError as exc:
+            bundle.parse_findings.append(Finding(name, "invalid-yaml", str(exc)[:200]))
+            continue
+        if not isinstance(fm, dict):
+            bundle.parse_findings.append(
+                Finding(name, "invalid-frontmatter", "frontmatter must be a mapping")
+            )
+            continue
+        bundle.frontmatter[name] = fm
+
+    if not bundle.files:
+        bundle.parse_findings.append(
+            Finding("<bundle>", "empty-bundle", f"no governance files found in {root}")
+        )
+    return bundle
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def _matcher_limits(node: object, depth: int = 1) -> tuple[int, int]:
+    """Return (max_depth, leaf_count) of a matcher tree."""
+    if not isinstance(node, dict):
+        return depth, 0
+    if "field" in node:
+        return depth, 1
+    children: list[object] = []
+    for key in ("all", "any"):
+        if key in node and isinstance(node[key], list):
+            children.extend(node[key])
+    if "not" in node:
+        children.append(node["not"])
+    max_d, leaves = depth, 0
+    for child in children:
+        d, n = _matcher_limits(child, depth + 1)
+        max_d = max(max_d, d)
+        leaves += n
+    return max_d, leaves
+
+
+def _iter_matchers(fname: str, fm: dict):
+    if fname == "policy.md":
+        for pol in fm.get("policies", []):
+            when = pol.get("when")
+            if isinstance(when, dict):
+                yield when
+    elif fname == "auth.md":
+        for entry in fm.get("requires_human", []):
+            when = entry.get("when")
+            if isinstance(when, dict):
+                yield when
+    elif fname == "escalation.md":
+        for route in fm.get("routes", []):
+            match = route.get("match")
+            if isinstance(match, dict):
+                yield match
+
+
+def _semantic_findings(fname: str, fm: dict) -> list[Finding]:
+    findings: list[Finding] = []
+
+    spec = fm.get("gaas_spec")
+    if spec not in SPEC_VERSIONS:
+        findings.append(
+            Finding(
+                fname,
+                "unsupported-spec-version",
+                f"gaas_spec {spec!r} not implemented (supported: {', '.join(SPEC_VERSIONS)})",
+            )
+        )
+
+    for tree in _iter_matchers(fname, fm):
+        depth, leaves = _matcher_limits(tree)
+        if depth > MAX_MATCHER_DEPTH:
+            findings.append(
+                Finding(fname, "matcher-too-deep", f"depth {depth} > {MAX_MATCHER_DEPTH}")
+            )
+        if leaves > MAX_MATCHER_LEAVES:
+            findings.append(
+                Finding(fname, "matcher-too-large", f"{leaves} leaves > {MAX_MATCHER_LEAVES}")
+            )
+
+    if fname == "escalation.md":
+        routes = {r.get("id"): r for r in fm.get("routes", []) if isinstance(r, dict)}
+        if "default" not in routes:
+            findings.append(
+                Finding(fname, "missing-default-route", "a route with id 'default' is required")
+            )
+        for rid, route in routes.items():
+            seen: set[str] = set()
+            cur: str | None = rid
+            while cur is not None:
+                if cur in seen:
+                    findings.append(
+                        Finding(fname, "escalation-cycle", f"timeout chain from {rid!r} cycles")
+                    )
+                    break
+                seen.add(cur)
+                r = routes.get(cur)
+                if r is None:
+                    findings.append(
+                        Finding(fname, "dangling-escalate-to", f"route {cur!r} does not exist")
+                    )
+                    break
+                cur = r.get("escalate_to") if r.get("on_timeout") == "escalate_up" else None
+
+    return findings
+
+
+def validate(bundle: GovernanceBundle) -> list[Finding]:
+    """Validate a parsed bundle. Empty list = conforming."""
+    findings = list(bundle.parse_findings)
+
+    orgs = set()
+    for fname, fm in bundle.frontmatter.items():
+        for err in _schema(fname).iter_errors(fm):
+            path = ".".join(str(p) for p in err.absolute_path) or "<root>"
+            findings.append(Finding(fname, "schema", f"{path}: {err.message[:160]}"))
+        findings.extend(_semantic_findings(fname, fm))
+        if isinstance(fm.get("org"), str):
+            orgs.add(fm["org"])
+
+    if len(orgs) > 1:
+        findings.append(
+            Finding("<bundle>", "org-mismatch", f"files declare different orgs: {sorted(orgs)}")
+        )
+
+    return findings

gaas_spec-0.1.0/gaas_spec/cli.py

@@ -0,0 +1,109 @@
+"""gaas — CLI for the auth.md governance file convention (spec 0.1).
+
+Local-only: no network, no API key. Suitable for CI.
+
+    gaas validate [path]           # validate a .gaas/ bundle (default: cwd)
+    gaas sign [path] --key k.pem --key-id my-key [--signer org]
+    gaas verify [path] --pub key_id=pub.pem [--pub ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .bundle import parse_bundle, validate
+from .signing import sign, verify
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    bundle = parse_bundle(args.path)
+    findings = validate(bundle)
+    for f in findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if findings:
+        print(f"\n{len(findings)} finding(s) — bundle does NOT conform to spec 0.1", file=sys.stderr)
+        return 1
+    print(f"✓ {len(bundle.files)} file(s) conform to spec 0.1: {', '.join(sorted(bundle.files))}")
+    return 0
+
+
+def _cmd_sign(args: argparse.Namespace) -> int:
+    bundle = parse_bundle(args.path)
+    findings = validate(bundle)
+    if findings:
+        print("refusing to sign a non-conforming bundle:", file=sys.stderr)
+        for f in findings:
+            print(f"  ✗ {f}", file=sys.stderr)
+        return 1
+    attestation = sign(
+        bundle,
+        Path(args.key).read_bytes(),
+        key_id=args.key_id,
+        signer=args.signer,
+    )
+    out = bundle.root / "attestation.sig"
+    out.write_text(json.dumps(attestation, indent=2) + "\n")
+    print(f"✓ wrote {out} (manifest_hash {attestation['manifest_hash'][:23]}…)")
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    bundle = parse_bundle(args.path)
+    att_path = bundle.root / "attestation.sig"
+    if not att_path.is_file():
+        print(f"✗ no attestation.sig in {bundle.root}", file=sys.stderr)
+        return 1
+    attestation = json.loads(att_path.read_text())
+    keys: dict[str, bytes] = {}
+    for spec in args.pub or []:
+        key_id, _, pem_path = spec.partition("=")
+        if not pem_path:
+            print(f"✗ --pub must be key_id=path.pem (got {spec!r})", file=sys.stderr)
+            return 2
+        keys[key_id] = Path(pem_path).read_bytes()
+    try:
+        results = verify(bundle, attestation, keys)
+    except ValueError as exc:
+        print(f"✗ {exc}", file=sys.stderr)
+        return 1
+    any_valid = False
+    for key_id, status in results.items():
+        mark = "✓" if status == "valid" else "✗"
+        print(f"  {mark} {key_id}: {status}")
+        any_valid |= status == "valid"
+    if not any_valid:
+        print("✗ no valid signature", file=sys.stderr)
+        return 1
+    print("✓ bundle verified")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="gaas", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("validate", help="validate a .gaas/ bundle")
+    p.add_argument("path", nargs="?", default=".")
+    p.set_defaults(func=_cmd_validate)
+
+    p = sub.add_parser("sign", help="sign a bundle -> attestation.sig")
+    p.add_argument("path", nargs="?", default=".")
+    p.add_argument("--key", required=True, help="ECDSA P-256 private key (PEM)")
+    p.add_argument("--key-id", required=True)
+    p.add_argument("--signer", choices=["org", "runtime"], default="org")
+    p.set_defaults(func=_cmd_sign)
+
+    p = sub.add_parser("verify", help="verify attestation.sig against the bundle")
+    p.add_argument("path", nargs="?", default=".")
+    p.add_argument("--pub", action="append", help="key_id=public.pem (repeatable)")
+    p.set_defaults(func=_cmd_verify)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

gaas_spec-0.1.0/gaas_spec/schemas/attestation.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gaas.to/spec/0.1/attestation.schema.json",
+  "title": "attestation.sig \u2014 spec 0.1",
+  "type": "object",
+  "$defs": {},
+  "properties": {
+    "gaas_spec": {
+      "const": "0.1"
+    },
+    "org": {
+      "type": "string",
+      "pattern": "^[a-z0-9_-]{1,64}$"
+    },
+    "manifest": {
+      "type": "object",
+      "patternProperties": {
+        "^(auth|policy|audit|escalation)\\.md$": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      },
+      "minProperties": 1,
+      "additionalProperties": false
+    },
+    "manifest_hash": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "algo": {
+      "const": "ES256"
+    },
+    "signatures": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "key_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "signer": {
+            "enum": [
+              "org",
+              "runtime"
+            ]
+          },
+          "sig": {
+            "type": "string",
+            "minLength": 1
+          },
+          "signed_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "key_id",
+          "signer",
+          "sig",
+          "signed_at"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "gaas_spec",
+    "org",
+    "manifest",
+    "manifest_hash",
+    "algo",
+    "signatures"
+  ],
+  "additionalProperties": false
+}