# hemo-hads — HADS v1: independent AI disclosure verification

HADS (Hemo AI Disclosure Standard) v1 verifies that a domain publicly and
verifiably implements AI-transparency controls aligned with the DUTIES IN
EU AI ACT ARTICLE 50: telling humans when they interact with AI, in their
language, with a route to a human. Verification verdicts are sealed into
the HELIOS provenance ledger.

## LEGAL FRAME (mandatory, applies to everything below)

HADS is an independent voluntary standard maintained by Fogeboro Digital Machines. HADS verification is NOT an official EU conformity assessment and NOT a certificate of AI Act compliance. EU AI Act Article 50 duties are self-executing; HADS verifies implementation of specific disclosure controls as of a verification date.

Full standard: https://github.com/fogennnnn/hads-spec

## States

- unverified   no record or never verified (badge: red)
- scanned      automated scan stored, owner not yet verified (badge: red)
- verified     all required controls passed, seal issued (badge: green)
- suspended    a previously verified domain failed its nightly rescan (badge: amber)
- revoked      operator-disabled (badge: red)

## Controls checked automatically (HADS v1 SPEC section 4)

- A1  ai_interaction_notice: disclosure file carries sv + en notice strings
      (minLength 16) AND the homepage entry point actually shows one of them
      verbatim (entity-decoded, whitespace-normalized) or via a
      data-hads-notice attribute (SPEC AU-09)
- A2  disclosure_file: /.well-known/ai-disclosure.json returns application/json,
      strict-parses, and validates against the HADS v1 schema: version=="1.0",
      entity.name/legal_person/contact, ai_systems >= 1 item, notices sv+en,
      redress.url + redress.email, synthetic_content_policy_url, generated_by,
      valid_within [scan date, scan date + 365d] (SPEC AU-01..AU-03)
- A3  synthetic_content_policy: synthetic_content_policy_url returns 200 as
      text/html or application/pdf with >= 2 controlled-vocabulary hits
      (C2PA / Content Credentials / provenance / syntetiskt / AI-genererat ...)
      (SPEC AU-05)
- A4  accountable_party: legal_person present AND contact route resolves —
      MX record for mail/email form, HTTP fetch for https URI (SPEC AU-07)
- A5  inventory: ai_systems >= 1 entry; each has name (unique case-insensitive),
      purpose >= 8 chars, interacts_with_humans === true
- A6  input_data_usage: input_data_usage_url is schema-optional but REQUIRED
      for A6 — absence is an automatic FAIL. When present: 200 html/pdf with
      >= 2 vocabulary hits (input/retention/training/tredjepart/...)
      (SPEC AU-08)
- A7  redress_channel: redress.url returns 200 with >= 1 redress-vocabulary hit
      (complaint/appeal/klagomål/överklaga...) AND redress.email domain has an
      MX record. Both required (SPEC AU-06 + AU-07)

Required for VERIFY: ALL SEVEN of A1-A7 pass (SPEC section 6.4 — no partial passes).
Homepage chatbot-marker heuristics additionally flag domains running AI features
with no disclosure file at all (sales signal; such scans fail A2/A3/A6).

## Endpoints

Base URL: https://hemo-hads.oooooooooo.se

GET  /scan/{domain}       public. Run all automated checks, store result, return full JSON breakdown. No auth (transparency).
POST /verify/{domain}     Bearer HELIOS token required. Re-runs checks; if required controls pass, seals a VERIFIED
                          attestation to HELIOS (Idempotency-Key hemo-hads:{domain}:{date}) and takes FIRST-VERIFIER
                          OWNERSHIP of the domain record (like hemo-registry). Later verify calls by other tokens -> 403.
GET  /status/{domain}     public. Current state, controls, badge data, seal verification URL.
GET  /badge/{domain}.svg  public. Color-coded SVG badge: green VERIFIED, amber SUSPENDED, red otherwise.
                          Every badge embeds the micro-disclaimer: "Independent verification - not EU certification".
POST /pack/{domain}       Bearer HELIOS token. Generate a Disclosure Pack: filled ai_disclosure.json template,
                          sv/en notice snippets, deployment instructions (Cloudflare + generic), remaining manual steps.
                          Body: {"entity_name":"...","contact":"email-or-url","systems":[{"name":"...","purpose":"..."}],
                          "notice_sv":"optional override","notice_en":"optional override"}
                          Query ?seal=1 also seals the generation event to HELIOS.
GET  /                    human dashboard (dark glass)
GET  /api/v1/report       totals: domains, states, sales triggers, last cron run
GET  /llms.txt            this file
GET  /robots.txt          allow all

## Continuous monitoring

Cron 30 03 UTC daily: re-scans up to 200 verified domains under a subrequest
budget. Any failing control suspends the seal (state -> suspended, reversible).
ONE consolidated alert email goes to the operator per affected run via
hemo-mail, hard-fused at max 2/day.

## Get a HELIOS token (for verify/pack)

POST https://ai.oooooooooo.se/api/v1/accounts   {"name":"my-agent"}   -> bearer token. Free.

## Example verify flow

1. Deploy your disclosure file (use POST /pack/{domain} to generate it).
2. POST https://hemo-hads.oooooooooo.se/verify/yourdomain.se  Authorization: Bearer <token>
3. On success you receive the seal id + a badge URL. Embed the badge.
4. Nightly rescans keep the seal honest; fix regressions and re-verify to lift a suspension.

## Disclosure file schema (what the scanner expects — SPEC section 5.2)

{
  "version": "1.0",
  "entity": { "name": "...", "legal_person": "...", "contact": "mailto:... or https://..." },
  "ai_systems": [ { "name": "...", "purpose": "... (>= 8 chars)", "interacts_with_humans": true } ],
  "notices": { "ai_interaction_text_sv": "...", "ai_interaction_text_en": "..." },
  "synthetic_content_policy_url": "https://...",
  "redress": { "url": "https://...", "email": "..." },
  "input_data_usage_url": "https://...",
  "generated_by": "...",
  "valid_until": "YYYY-MM-DD"
}

## Totals right now

domains_scanned=3 verified=0 suspended=0 sales_triggers=0