@aiacta-org/ai-attribution-lint 1.0.0

package/README.md

@@ -0,0 +1,167 @@
+# @aiacta-org/ai-attribution-lint
+
+> CLI validator for `ai-attribution.txt` files — the AIACTA open standard for AI content attribution (Proposal 4, §5.7).
+
+[![npm version](https://img.shields.io/npm/v/@aiacta-org/ai-attribution-lint.svg)](https://www.npmjs.com/package/@aiacta-org/ai-attribution-lint)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
+[![AIACTA Spec](https://img.shields.io/badge/spec-AIACTA%2F1.0-orange.svg)](../../docs/proposals/proposal-4-ai-attribution-txt.md)
+
+---
+
+## What is this?
+
+`@aiacta-org/ai-attribution-lint` validates your `ai-attribution.txt` file — the plain-text file publishers place on their website to declare their preferences to AI systems. It checks syntax, required fields, valid values, SPDX licence identifiers, and webhook reachability.
+
+Think of it as the `eslint` for the AIACTA standard.
+
+---
+
+## Install
+
+```bash
+# Run once without installing (recommended for quick checks)
+npx @aiacta-org/ai-attribution-lint https://yourdomain.com
+
+# Install globally
+npm install -g @aiacta-org/ai-attribution-lint
+
+# Install as a dev dependency in a project
+npm install --save-dev @aiacta-org/ai-attribution-lint
+```
+
+---
+
+## Usage
+
+### Check a live website
+
+```bash
+npx @aiacta-org/ai-attribution-lint https://yourdomain.com
+```
+
+The linter automatically fetches `/.well-known/ai-attribution.txt` (and falls back to `/ai-attribution.txt`).
+
+### Check a local file
+
+```bash
+npx @aiacta-org/ai-attribution-lint ./ai-attribution.txt
+```
+
+### JSON output (for CI pipelines)
+
+```bash
+npx @aiacta-org/ai-attribution-lint https://yourdomain.com --json
+```
+
+Output format:
+```json
+{
+  "errors": [],
+  "warnings": [
+    "Schema-Version is missing — defaults to 1.0"
+  ],
+  "info": []
+}
+```
+
+Exit codes:
+- `0` — Passed (no errors)
+- `1` — Failed (one or more errors, or warnings in `--strict` mode)
+- `2` — Could not fetch or parse the file
+
+### Strict mode (treat warnings as errors)
+
+```bash
+npx @aiacta-org/ai-attribution-lint https://yourdomain.com --strict
+```
+
+---
+
+## What it checks
+
+| Rule | Severity |
+|------|----------|
+| `Schema-Version` is present and is `"1.0"` | Warning if missing |
+| `Contact` field is present | Warning if missing |
+| `Allow-Purpose` / `Disallow-Purpose` values are valid enum values (`training`, `rag`, `index`, `quality-eval`) | Error |
+| `Content-License` is a valid SPDX identifier or `All-Rights-Reserved` | Error |
+| `Citation-Webhook` URL is reachable (HTTP HEAD request) | Warning if unreachable |
+| `Reward-Tier` is a valid enum value | Error |
+| `robots.txt` conflicts with `Allow-Purpose` | Warning |
+| Unknown fields are silently ignored (forward-compatibility per §5.6) | — |
+
+---
+
+## Use in CI/CD
+
+Add to your GitHub Actions workflow to validate your `ai-attribution.txt` on every deploy:
+
+```yaml
+- name: Validate ai-attribution.txt
+  run: npx @aiacta-org/ai-attribution-lint https://yourdomain.com --json
+```
+
+Or validate a local file during build:
+
+```yaml
+- name: Validate ai-attribution.txt
+  run: npx @aiacta-org/ai-attribution-lint ./public/.well-known/ai-attribution.txt
+```
+
+---
+
+## Node.js API
+
+```javascript
+const { lint } = require('@aiacta-org/ai-attribution-lint');
+
+const result = await lint('https://yourdomain.com');
+// or: await lint('./ai-attribution.txt')
+
+console.log(result.errors);   // string[] — blocking issues
+console.log(result.warnings); // string[] — advisory issues
+console.log(result.info);     // string[] — informational notes
+
+if (result.errors.length > 0) {
+  process.exit(1);
+}
+```
+
+---
+
+## Example ai-attribution.txt
+
+```
+Schema-Version: 1.0
+Contact: ai-licensing@yourdomain.com
+Preferred-Attribution: Your Publication Name (yourdomain.com)
+Allow-Purpose: rag
+Allow-Purpose: index
+Disallow-Purpose: training
+Require-Citation: true
+Require-Source-Link: true
+Citation-Format: title-and-url
+Citation-Webhook: https://yourdomain.com/webhooks/ai-citations
+Recrawl-After: 24h
+Reward-Tier: standard
+Content-License: All-Rights-Reserved
+```
+
+Place this file at `https://yourdomain.com/.well-known/ai-attribution.txt`.
+
+---
+
+## Related packages
+
+| Package | Purpose |
+|---------|---------|
+| [`@aiacta-org/ai-citation-sdk`](https://www.npmjs.com/package/@aiacta-org/ai-citation-sdk) | Receive and verify citation webhook events |
+| [`@aiacta-org/crawl-manifest-client`](https://www.npmjs.com/package/@aiacta-org/crawl-manifest-client) | Query AI providers' crawl history for your domain |
+
+---
+
+## License & Copyright
+
+Copyright © 2026 Eric Michel, PhD. Licensed under the [Apache License 2.0](../../LICENSE).
+
+AIACTA™ is part of the [AIACTA open standard](https://github.com/aiacta-org/aiacta).

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@aiacta-org/ai-attribution-lint",
+  "version": "1.0.0",
+  "description": "CLI validator for ai-attribution.txt files (AIACTA Proposal 4 §5.7)",
+  "author": "Eric Michel",
+  "license": "Apache-2.0",
+  "bin": { "ai-attribution-lint": "./src/cli.js" },
+  "main": "./src/index.js",
+  "scripts": { "test": "jest" },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "spdx-license-ids": "^3.0.0",
+    "chalk": "^5.0.0",
+    "yargs": "^17.0.0"
+  },
+  "devDependencies": { "jest": "^29.0.0" }
+}

package/src/cli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * ai-attribution-lint CLI entry point (§5.7)
+ * Usage: npx ai-attribution-lint <url|file>
+ */
+'use strict';
+const yargs = require('yargs');
+const { lint } = require('./index');
+
+const argv = yargs
+  .usage('Usage: $0 <url|path>')
+  .option('json', { type: 'boolean', description: 'Output results as JSON' })
+  .option('strict', { type: 'boolean', description: 'Exit 1 on warnings' })
+  .demandCommand(1)
+  .help()
+  .argv;
+
+lint(argv._[0], { json: argv.json, strict: argv.strict })
+  .then(result => {
+    if (argv.json) { console.log(JSON.stringify(result, null, 2)); }
+    process.exit(result.errors.length > 0 || (argv.strict && result.warnings.length > 0) ? 1 : 0);
+  })
+  .catch(err => { console.error(err.message); process.exit(2); });

package/src/fetcher.js

@@ -0,0 +1,27 @@
+/**
+ * Fetches ai-attribution.txt from a URL or reads from a local file path.
+ * Respects Cache-Control / Expires headers as per §5.2.
+ */
+'use strict';
+const axios = require('axios');
+const fs = require('fs');
+
+async function fetchContent(target) {
+  if (target.startsWith('http://') || target.startsWith('https://')) {
+    // Try well-known location first (RFC 8615), fall back to root (§5.2)
+    const urls = [
+      target.replace(/\/?$/, '/.well-known/ai-attribution.txt'),
+      target.replace(/\/?$/, '/ai-attribution.txt'),
+    ];
+    for (const url of urls) {
+      try {
+        const res = await axios.get(url, { timeout: 10_000, responseType: 'text' });
+        if (res.status === 200) return res.data;
+      } catch (_) { /* try next */ }
+    }
+    throw new Error(`Could not fetch ai-attribution.txt from ${target}`);
+  }
+  return fs.readFileSync(target, 'utf-8');
+}
+
+module.exports = { fetchContent };

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * ai-attribution-lint — public API
+ * Returns { errors: [], warnings: [], info: [] } for a given URL or file path.
+ */
+'use strict';
+const { fetchContent } = require('./fetcher');
+const { parse } = require('./parser');
+const { runRules } = require('./runner');
+
+async function lint(target, opts = {}) {
+  const raw = await fetchContent(target);
+  const parsed = parse(raw);
+  return await runRules(parsed, target, opts);
+}
+
+module.exports = { lint };

package/src/parser.js

@@ -0,0 +1,72 @@
+/**
+ * Parses the key: value line format of ai-attribution.txt (§5.3).
+ *
+ * Rules:
+ *  - Lines starting with # are comments; blank lines are skipped.
+ *  - Field names are case-insensitive (normalised to title-case key names).
+ *  - Multi-value fields (Contact, Allow-Purpose, Disallow-Purpose) accumulate
+ *    into arrays; all other fields take the last occurrence.
+ *  - Unknown fields are silently ignored for forward-compatibility (§5.6).
+ */
+'use strict';
+
+// Fields that may appear multiple times and accumulate as arrays (§5.3)
+const MULTI_VALUE_FIELDS = new Set([
+  'Contact',
+  'Allow-Purpose',
+  'Disallow-Purpose',
+]);
+
+// Canonical field names — normalises alternate casings to the spec names
+const CANONICAL = {
+  'schema-version':       'Schema-Version',
+  'contact':              'Contact',
+  'preferred-attribution':'Preferred-Attribution',
+  'canonical-author':     'Canonical-Author',
+  'allow-purpose':        'Allow-Purpose',
+  'disallow-purpose':     'Disallow-Purpose',
+  'require-citation':     'Require-Citation',
+  'require-source-link':  'Require-Source-Link',
+  'citation-format':      'Citation-Format',
+  'allow-utm-append':     'Allow-UTM-Append',
+  'preferred-utm-source': 'Preferred-UTM-Source',
+  'citation-webhook':     'Citation-Webhook',
+  'recrawl-after':        'Recrawl-After',
+  'licensing-contact':    'Licensing-Contact',
+  'licensing-url':        'Licensing-URL',
+  'reward-tier':          'Reward-Tier',
+  'content-license':      'Content-License',
+};
+
+/**
+ * Parse raw ai-attribution.txt content into a structured object.
+ *
+ * @param {string} raw  Raw file content
+ * @returns {object}    Parsed key/value map
+ */
+function parse(raw) {
+  const result = {};
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const colon = trimmed.indexOf(':');
+    if (colon === -1) continue;
+
+    const rawKey = trimmed.slice(0, colon).trim();
+    const value  = trimmed.slice(colon + 1).trim();
+    if (!value) continue;
+
+    // Normalise key
+    const key = CANONICAL[rawKey.toLowerCase()] || rawKey;
+
+    if (MULTI_VALUE_FIELDS.has(key)) {
+      result[key] = result[key] ? [...result[key], value] : [value];
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+module.exports = { parse, MULTI_VALUE_FIELDS, CANONICAL };

package/src/rules/contact.js

@@ -0,0 +1,9 @@
+/** Rule: At least one Contact field should be present (§5.4). */
+'use strict';
+module.exports = function ruleContact(parsed) {
+  const warnings = [];
+  if (!parsed['Contact'] || parsed['Contact'].length === 0) {
+    warnings.push('No Contact field found; publishers should provide a licensing contact');
+  }
+  return { errors: [], warnings };
+};

package/src/rules/index.js

@@ -0,0 +1,11 @@
+/** Aggregates all validation rules. Order matters — later rules may depend on earlier parsing. */
+'use strict';
+module.exports = [
+  require('./schema-version'),
+  require('./contact'),
+  require('./purpose'),
+  require('./spdx-license'),
+  require('./webhook-reachability'),
+  require('./reward-tier'),
+  require('./robots-txt-conflict'),
+];

package/src/rules/purpose.js

@@ -0,0 +1,21 @@
+/** Rule: Allow-Purpose and Disallow-Purpose must use valid enum values (§5.4). */
+'use strict';
+const VALID = new Set(['training', 'rag', 'index', 'quality-eval']);
+function validatePurposeField(values, fieldName) {
+  const errors = [];
+  for (const v of (values || [])) {
+    if (!VALID.has(v.toLowerCase())) {
+      errors.push(`Invalid ${fieldName} value "${v}"; allowed: ${[...VALID].join(', ')}`);
+    }
+  }
+  return errors;
+}
+module.exports = function rulePurpose(parsed) {
+  return {
+    errors: [
+      ...validatePurposeField(parsed['Allow-Purpose'], 'Allow-Purpose'),
+      ...validatePurposeField(parsed['Disallow-Purpose'], 'Disallow-Purpose'),
+    ],
+    warnings: [],
+  };
+};

package/src/rules/reward-tier.js

@@ -0,0 +1,11 @@
+/** Rule: Reward-Tier must be a valid enum value (§5.4). */
+'use strict';
+const VALID = new Set(['standard', 'premium', 'licensing-only', 'none']);
+module.exports = function ruleRewardTier(parsed) {
+  const errors = [];
+  const tier = parsed['Reward-Tier'];
+  if (tier && !VALID.has(tier.toLowerCase())) {
+    errors.push(`Invalid Reward-Tier "${tier}"; allowed: ${[...VALID].join(', ')}`);
+  }
+  return { errors, warnings: [] };
+};

package/src/rules/robots-txt-conflict.js

@@ -0,0 +1,73 @@
+/**
+ * Rule: robots.txt conflict checker (§5.5).
+ *
+ * Verifies that ai-attribution.txt Allow-Purpose directives do not conflict
+ * with Disallow rules in the site's robots.txt, since robots.txt Disallow
+ * takes precedence over ai-attribution.txt Allow-Purpose.
+ *
+ * Issues a WARNING (not error) because robots.txt may be intentionally
+ * restrictive while ai-attribution.txt is aspirational.
+ */
+'use strict';
+const axios = require('axios');
+const { URL } = require('url');
+
+const KNOWN_AI_BOTS = ['GPTBot', 'ClaudeBot', 'Google-Extended', 'PerplexityBot', 'Grok-Bot'];
+
+/**
+ * Minimally parses a robots.txt to extract Disallow rules for known AI bots.
+ * Not a full RFC 9309 parser — only checks direct bot-name matches.
+ * @param {string} robotsTxt
+ * @returns {Set<string>}  Set of disallowed path prefixes for AI bots
+ */
+function parseRobotsForAiBots(robotsTxt) {
+  const disallowed = new Set();
+  const lines = robotsTxt.split('\n').map(l => l.trim());
+  let inAiBlock = false;
+
+  for (const line of lines) {
+    if (line.startsWith('#') || !line) { inAiBlock = false; continue; }
+    if (line.toLowerCase().startsWith('user-agent:')) {
+      const ua = line.slice('user-agent:'.length).trim();
+      inAiBlock = ua === '*' || KNOWN_AI_BOTS.some(b => ua.toLowerCase().includes(b.toLowerCase()));
+      continue;
+    }
+    if (inAiBlock && line.toLowerCase().startsWith('disallow:')) {
+      const path = line.slice('disallow:'.length).trim();
+      if (path) disallowed.add(path);
+    }
+  }
+  return disallowed;
+}
+
+module.exports = async function ruleRobotsTxtConflict(parsed, target) {
+  const warnings = [];
+  const info     = [];
+  const allowPurpose = parsed['Allow-Purpose'] || [];
+
+  if (allowPurpose.length === 0) return { errors: [], warnings, info };
+  if (!target || !target.startsWith('http')) return { errors: [], warnings, info };
+
+  try {
+    const origin    = new URL(target.replace(/\/?\.well-known.*$/, '').replace(/\/ai-attribution\.txt$/, '')).origin;
+    const robotsUrl = `${origin}/robots.txt`;
+    const res = await axios.get(robotsUrl, { timeout: 8_000, responseType: 'text' });
+    const disallowed = parseRobotsForAiBots(res.data);
+
+    if (disallowed.has('/') || disallowed.has('/*')) {
+      warnings.push(
+        `robots.txt Disallow: / blocks all AI bots, overriding Allow-Purpose: ${allowPurpose.join(', ')} (§5.5). ` +
+        `AI systems will respect robots.txt first.`
+      );
+    } else if (disallowed.size > 0) {
+      info.push(
+        `robots.txt restricts AI bots from ${disallowed.size} path(s): ${[...disallowed].slice(0,3).join(', ')}` +
+        `${disallowed.size > 3 ? '...' : ''}. These restrictions override ai-attribution.txt Allow-Purpose (§5.5).`
+      );
+    }
+  } catch (e) {
+    info.push(`Could not fetch robots.txt for conflict check: ${e.message}`);
+  }
+
+  return { errors: [], warnings, info };
+};

package/src/rules/schema-version.js

@@ -0,0 +1,11 @@
+/** Rule: Schema-Version must be present and parseable (§5.4). */
+'use strict';
+module.exports = function ruleSchemaVersion(parsed) {
+  const errors = [], warnings = [];
+  if (!parsed['Schema-Version']) {
+    warnings.push('Schema-Version field missing; assuming 1.0');
+  } else if (parsed['Schema-Version'] !== '1.0') {
+    warnings.push(`Unknown Schema-Version "${parsed['Schema-Version']}"; parser may not support all fields`);
+  }
+  return { errors, warnings };
+};

package/src/rules/spdx-license.js

@@ -0,0 +1,11 @@
+/** Rule: Content-License must be a valid SPDX identifier (§5.4, §10.3). */
+'use strict';
+const spdxIds = require('spdx-license-ids');
+module.exports = function ruleSpdxLicense(parsed) {
+  const errors = [], warnings = [];
+  const lic = parsed['Content-License'];
+  if (lic && lic !== 'All-Rights-Reserved' && !spdxIds.includes(lic)) {
+    errors.push(`Content-License "${lic}" is not a valid SPDX identifier. See https://spdx.org/licenses/`);
+  }
+  return { errors, warnings };
+};

package/src/rules/webhook-reachability.js

@@ -0,0 +1,23 @@
+/**
+ * Rule: Citation-Webhook endpoint should be reachable and on the same domain (§6.3).
+ * Issues a WARNING (not error) for network failures since CI may run offline.
+ */
+'use strict';
+const axios = require('axios');
+const { URL } = require('url');
+module.exports = async function ruleWebhookReachability(parsed, target) {
+  const warnings = [];
+  const endpoint = parsed['Citation-Webhook'];
+  if (!endpoint) return { errors: [], warnings };
+  try {
+    const webhookHost = new URL(endpoint).hostname;
+    const targetHost = target.startsWith('http') ? new URL(target).hostname : null;
+    if (targetHost && webhookHost !== targetHost && !webhookHost.endsWith(`.${targetHost}`)) {
+      warnings.push(`Citation-Webhook host "${webhookHost}" differs from target domain "${targetHost}" — DNS verification required (§6.3)`);
+    }
+    await axios.head(endpoint, { timeout: 5_000 });
+  } catch (e) {
+    warnings.push(`Citation-Webhook endpoint not reachable: ${endpoint} (${e.message})`);
+  }
+  return { errors: [], warnings };
+};

package/src/runner.js

@@ -0,0 +1,24 @@
+/**
+ * Runs all validation rules against the parsed config and returns results.
+ *
+ * Rules may be sync or async (e.g. webhook-reachability does a network call).
+ * We await all rules so async ones — like ruleWebhookReachability — actually
+ * run to completion instead of silently returning an unresolved Promise.
+ */
+'use strict';
+const rules = require('./rules');
+
+async function runRules(parsed, target, opts) {
+  const errors = [], warnings = [], info = [];
+  for (const rule of rules) {
+    // await handles both sync rules (returns plain object) and
+    // async rules (returns Promise<object>) uniformly
+    const findings = await rule(parsed, target);
+    errors.push(...(findings.errors || []));
+    warnings.push(...(findings.warnings || []));
+    info.push(...(findings.info || []));
+  }
+  return { errors, warnings, info };
+}
+
+module.exports = { runRules };

package/tests/parser.test.js

@@ -0,0 +1,14 @@
+const { parse } = require('../src/parser');
+
+test('parses basic fields', () => {
+  const raw = 'Schema-Version: 1.0\nContact: licensing@example.com\nAllow-Purpose: rag\nAllow-Purpose: index';
+  const result = parse(raw);
+  expect(result['Schema-Version']).toBe('1.0');
+  expect(result['Contact']).toEqual(['licensing@example.com']);
+  expect(result['Allow-Purpose']).toEqual(['rag', 'index']);
+});
+
+test('ignores comments and blank lines', () => {
+  const raw = '# comment\n\nSchema-Version: 1.0';
+  expect(parse(raw)['Schema-Version']).toBe('1.0');
+});

package/tests/robots-conflict.test.js

@@ -0,0 +1,17 @@
+/**
+ * Tests for the robots.txt conflict rule (§5.5).
+ * Uses nock to mock robots.txt responses.
+ */
+const ruleRobotsTxtConflict = require('../src/rules/robots-txt-conflict');
+
+// Test with a local file path (no robots.txt fetch attempted)
+test('skips robots check for local file paths', async () => {
+  const r = await ruleRobotsTxtConflict({ 'Allow-Purpose': ['rag'] }, '/local/path/ai-attribution.txt');
+  expect(r.errors).toHaveLength(0);
+});
+
+test('skips robots check when no Allow-Purpose set', async () => {
+  const r = await ruleRobotsTxtConflict({}, 'https://example.com');
+  expect(r.errors).toHaveLength(0);
+  expect(r.warnings).toHaveLength(0);
+});

package/tests/rules.test.js

@@ -0,0 +1,17 @@
+const ruleSchemaVersion = require('../src/rules/schema-version');
+const ruleSpdxLicense   = require('../src/rules/spdx-license');
+
+test('schema-version warns when missing', () => {
+  const r = ruleSchemaVersion({});
+  expect(r.warnings.length).toBeGreaterThan(0);
+});
+
+test('spdx-license errors on unknown identifier', () => {
+  const r = ruleSpdxLicense({ 'Content-License': 'INVALID-ID' });
+  expect(r.errors.length).toBe(1);
+});
+
+test('spdx-license passes on All-Rights-Reserved', () => {
+  const r = ruleSpdxLicense({ 'Content-License': 'All-Rights-Reserved' });
+  expect(r.errors.length).toBe(0);
+});