@ixo/domain.md 0.3.0

package/src/templates/resolver.ts

@@ -0,0 +1,200 @@
+import { lookup } from 'node:dns/promises';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { request } from 'node:https';
+import { relative, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import ipaddr from 'ipaddr.js';
+
+import type {
+  ResolvedTemplateResource,
+  TemplateResolver,
+  TemplateResolverContext,
+} from './types.js';
+
+function isPublicAddress(address: string): boolean {
+  const parsed = ipaddr.parse(address);
+  const range = parsed.range();
+  return range === 'unicast';
+}
+
+export function validateHttpsTarget(url: URL, addresses: string[] = []): void {
+  if (url.protocol !== 'https:') throw new Error('Only HTTPS template retrieval is allowed.');
+  if (url.username || url.password) throw new Error('Credentials in template URLs are forbidden.');
+  if (!url.hostname) throw new Error('Template URL hostname is required.');
+  if (addresses.some((address) => !isPublicAddress(address))) {
+    throw new Error(`Template hostname ${url.hostname} resolves to a non-public address.`);
+  }
+}
+
+export class FileTemplateResolver implements TemplateResolver {
+  supports(uri: string): boolean {
+    return uri.startsWith('file:') || !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(uri);
+  }
+
+  async resolve(uri: string, context: TemplateResolverContext): Promise<ResolvedTemplateResource> {
+    const path = resolve(uri.startsWith('file:') ? fileURLToPath(uri) : uri);
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+      throw new Error('Template resources must be regular files, not symlinks.');
+    if (stat.size > context.maxBytes)
+      throw new Error(`Template resource exceeds ${context.maxBytes} bytes.`);
+    const canonical = await realpath(path);
+    if (canonical !== path) throw new Error('Template resource paths must not contain symlinks.');
+    return { uri: pathToFileURL(canonical).href, bytes: await readFile(canonical) };
+  }
+
+  static async resolveRelative(manifestUri: string, logicalPath: string): Promise<string> {
+    const manifestPath = fileURLToPath(manifestUri);
+    const root = await realpath(resolve(manifestPath, '..'));
+    const requested = resolve(root, logicalPath);
+    const lexicalTraversal = relative(root, requested);
+    if (
+      lexicalTraversal.startsWith('..') ||
+      lexicalTraversal.startsWith('/') ||
+      lexicalTraversal === ''
+    ) {
+      throw new Error(`Template path escapes or aliases the manifest root: ${logicalPath}`);
+    }
+    let current = root;
+    for (const component of lexicalTraversal.split(/[\\/]/)) {
+      current = resolve(current, component);
+      if ((await lstat(current)).isSymbolicLink())
+        throw new Error(`Template path contains a symlink: ${logicalPath}`);
+    }
+    const target = await realpath(requested);
+    const traversal = relative(root, target);
+    if (traversal.startsWith('..') || traversal.startsWith('/') || traversal === '') {
+      throw new Error(`Template path escapes or aliases the manifest root: ${logicalPath}`);
+    }
+    return pathToFileURL(target).href;
+  }
+}
+
+interface HttpsResolverOptions {
+  maxRedirects?: number;
+}
+
+export class HttpsTemplateResolver implements TemplateResolver {
+  readonly maxRedirects: number;
+
+  constructor(options: HttpsResolverOptions = {}) {
+    this.maxRedirects = options.maxRedirects ?? 3;
+  }
+
+  supports(uri: string): boolean {
+    return uri.startsWith('https:');
+  }
+
+  async resolve(uri: string, context: TemplateResolverContext): Promise<ResolvedTemplateResource> {
+    return this.fetch(new URL(uri), context, 0);
+  }
+
+  private async fetch(
+    url: URL,
+    context: TemplateResolverContext,
+    redirects: number,
+  ): Promise<ResolvedTemplateResource> {
+    validateHttpsTarget(url);
+    const addresses = await lookup(url.hostname, { all: true, verbatim: true });
+    if (addresses.length === 0)
+      throw new Error(`Template hostname ${url.hostname} did not resolve.`);
+    validateHttpsTarget(
+      url,
+      addresses.map((entry) => entry.address),
+    );
+    const approved = addresses[0];
+    if (!approved) throw new Error(`Template hostname ${url.hostname} did not resolve.`);
+
+    return new Promise((resolvePromise, reject) => {
+      const req = request(
+        url,
+        {
+          headers: { accept: 'application/yaml, application/json, text/markdown, text/plain' },
+          lookup(_hostname, _options, callback) {
+            callback(null, approved.address, approved.family);
+          },
+          servername: url.hostname,
+        },
+        (response) => {
+          const status = response.statusCode ?? 0;
+          const location = response.headers.location;
+          if (status >= 300 && status < 400 && location) {
+            response.resume();
+            if (redirects >= this.maxRedirects) {
+              reject(new Error('Template retrieval exceeded the redirect limit.'));
+              return;
+            }
+            const redirected = new URL(location, url);
+            this.fetch(redirected, context, redirects + 1).then(resolvePromise, reject);
+            return;
+          }
+          if (status !== 200) {
+            response.resume();
+            reject(new Error(`Template retrieval returned HTTP ${status}.`));
+            return;
+          }
+          const chunks: Buffer[] = [];
+          let size = 0;
+          response.on('data', (chunk: Buffer) => {
+            size += chunk.length;
+            if (size > context.maxBytes) {
+              req.destroy(new Error(`Template resource exceeds ${context.maxBytes} bytes.`));
+              return;
+            }
+            chunks.push(chunk);
+          });
+          response.on('end', () => {
+            resolvePromise({
+              uri: url.href,
+              bytes: Buffer.concat(chunks),
+              ...(typeof response.headers['content-type'] === 'string'
+                ? { mediaType: response.headers['content-type'] }
+                : {}),
+            });
+          });
+        },
+      );
+      req.setTimeout(context.timeoutMs, () =>
+        req.destroy(new Error('Template retrieval timed out.')),
+      );
+      req.on('error', reject);
+      req.end();
+    });
+  }
+}
+
+export class IpfsTemplateResolver implements TemplateResolver {
+  private readonly gateway: URL;
+  private readonly https: HttpsTemplateResolver;
+
+  constructor(gateway: string, httpsResolver = new HttpsTemplateResolver()) {
+    this.gateway = new URL(gateway.endsWith('/') ? gateway : `${gateway}/`);
+    validateHttpsTarget(this.gateway);
+    this.https = httpsResolver;
+  }
+
+  supports(uri: string): boolean {
+    return uri.startsWith('ipfs:');
+  }
+
+  async resolve(uri: string, context: TemplateResolverContext): Promise<ResolvedTemplateResource> {
+    const source = new URL(uri);
+    const cid = source.hostname;
+    if (!cid) throw new Error('IPFS URI must include a CID host.');
+    const path = source.pathname.replace(/^\/+/, '');
+    const target = new URL(`ipfs/${cid}/${path}`, this.gateway);
+    const result = await this.https.resolve(target.href, context);
+    return { ...result, uri };
+  }
+}
+
+export function relativeTemplateUri(manifestUri: string, logicalPath: string): string {
+  if (manifestUri.startsWith('ipfs:')) {
+    const base = new URL(manifestUri);
+    const root = base.pathname.slice(0, base.pathname.lastIndexOf('/') + 1);
+    base.pathname = `${root}${logicalPath}`;
+    return base.href;
+  }
+  return new URL(logicalPath, manifestUri).href;
+}

package/src/templates/types.ts

@@ -0,0 +1,98 @@
+import type { LintReport } from '../types.js';
+
+export type TemplateRole =
+  | 'domain.md'
+  | 'description'
+  | 'changelog'
+  | 'manifest'
+  | 'playbook'
+  | 'schema'
+  | 'resource'
+  | 'policy'
+  | 'supporting';
+
+export type TemplateDerivedType =
+  | 'dao'
+  | 'organisation'
+  | 'project'
+  | 'asset'
+  | 'deed'
+  | 'investment'
+  | 'oracle'
+  | 'service'
+  | 'dataset'
+  | 'device'
+  | 'place'
+  | 'portfolio'
+  | 'marketplace'
+  | 'pod'
+  | 'claim_collection'
+  | 'custom';
+
+export interface TemplateFileRecord {
+  role: TemplateRole;
+  path: string;
+  media_type: 'text/markdown' | 'application/yaml' | 'application/json' | 'text/plain';
+  max_bytes: number;
+  uri?: string;
+  cid?: string | null;
+  sha256?: string | null;
+  required: boolean;
+}
+
+export interface TemplateBundleRecord {
+  derived_type: TemplateDerivedType;
+  bundle_version: string;
+  files: TemplateFileRecord[];
+}
+
+export interface TemplateManifest {
+  version: '1.0.0-rc.3';
+  kind: 'domain.md/template-manifest';
+  protocol: string;
+  protocol_version: string;
+  bundles: TemplateBundleRecord[];
+}
+
+export interface ResolvedTemplateResource {
+  uri: string;
+  bytes: Uint8Array;
+  mediaType?: string;
+}
+
+export interface TemplateResolverContext {
+  maxBytes: number;
+  timeoutMs: number;
+}
+
+export interface TemplateResolver {
+  supports(uri: string): boolean;
+  resolve(uri: string, context: TemplateResolverContext): Promise<ResolvedTemplateResource>;
+}
+
+export interface RenderTemplateRequest {
+  manifestUri: string;
+  expectedProtocol: string;
+  derivedType: TemplateDerivedType;
+  parameters: Record<string, unknown>;
+  manifestSha256?: string;
+  manifestCid?: string;
+  ipfsGateway?: string;
+  resolvers?: TemplateResolver[];
+  timeoutMs?: number;
+}
+
+export interface RenderedFile {
+  role: string;
+  path: string;
+  bytes: Uint8Array;
+  sha256: string;
+  sourceUri: string;
+}
+
+export interface RenderTemplateResult {
+  files: RenderedFile[];
+  provenance: string;
+  report: LintReport;
+  manifest: TemplateManifest;
+}

package/src/types.ts

@@ -0,0 +1,195 @@
+export type Severity = 'error' | 'warning' | 'info';
+export type ConformanceProfile = 'authoring_draft' | 'persisted_draft' | 'anchored' | 'runtime';
+export type DomainMode = 'derived' | 'protocol' | 'standalone';
+export type DomainRecord = Record<string, unknown>;
+
+export interface SourceLocation {
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export interface Finding {
+  severity: Severity;
+  code: string;
+  message: string;
+  path: string;
+  location: SourceLocation;
+  remediation?: string;
+}
+
+export interface DomainSection {
+  heading: string;
+  content: string;
+  location: SourceLocation;
+}
+
+export interface DomainDocument {
+  frontmatter: DomainRecord;
+  sections: DomainSection[];
+  sourceName: string;
+  raw: string;
+}
+
+export interface ParseOptions {
+  sourceName?: string;
+  maxBytes?: number;
+}
+
+export interface ParseResult {
+  ok: boolean;
+  document?: DomainDocument;
+  findings: Finding[];
+}
+
+export interface LintOptions extends ParseOptions {
+  expectedProfile?: ConformanceProfile;
+}
+
+export interface FindingSummary {
+  errors: number;
+  warnings: number;
+  infos: number;
+}
+
+export interface ExternalCheck {
+  code: string;
+  category: 'integrity' | 'identity' | 'authorization' | 'time' | 'chain';
+  reason: string;
+}
+
+export type ConstitutionStatus =
+  'not_applicable' | 'draft' | 'adopted' | 'in_force' | 'suspended' | 'superseded';
+
+export type ConstitutionalInstrumentFunction =
+  'constitutive' | 'governing' | 'amending' | 'interpretive' | 'executable';
+
+export interface LegalEffect {
+  status: 'none' | 'claimed' | 'verified' | 'unknown';
+  jurisdiction: string | null;
+  authority_evidence: string[];
+}
+
+export interface ConstitutionalInstrument {
+  document_ref: string;
+  type: string;
+  functions: ConstitutionalInstrumentFunction[];
+  canonical: boolean;
+  effective_from: string | null;
+  effective_until: string | null;
+}
+
+export interface ConstitutionalGovernance {
+  authority_sources: string[];
+  decision_procedure: string | null;
+  amendment_procedure: string | null;
+  interpretation_procedure: string | null;
+  dispute_resolution_procedure: string | null;
+  suspension_procedure: string | null;
+  dissolution_procedure: string | null;
+}
+
+export interface ConstitutionalExecution {
+  mode: 'human_interpreted' | 'machine_assisted' | 'machine_executable' | 'hybrid';
+  implementations: string[];
+  conformance_tests: string[];
+  enforcement_points: string[];
+  failure_policy: 'deny' | 'pause_and_escalate';
+  human_review_required_for: string[];
+}
+
+export interface ConstitutionalAI {
+  mode: 'none' | 'context_only' | 'critique_and_revise' | 'policy_evaluate' | 'hybrid';
+  applies_to_agents: string[];
+  principles: string[];
+  critique_procedure: string | null;
+  revision_procedure: string | null;
+  decision_procedure: string | null;
+  model_profile: string | null;
+  conflict_policy: 'canonical_authority_prevails';
+  audit_record: string | null;
+}
+
+export interface ConstitutionalSubjectProfile {
+  subject_types: string[];
+  archetypes: string[];
+  identity: string[];
+  purposes: string[];
+  interests: string[];
+  values: string[];
+  rights: string[];
+  obligations: string[];
+  capabilities: string[];
+  claims: string[];
+  wallets: string[];
+  authorities: string[];
+  memory: string[];
+  evidence_policies: string[];
+  evaluation_policies: string[];
+  decision_policies: string[];
+  settlement_policies: string[];
+  governance: string[];
+  custodians: string[];
+  stewards: string[];
+  owners: string[];
+  beneficiaries: string[];
+  oracles: string[];
+  agentic_twins: string[];
+}
+
+export interface ConstitutionDeclaration {
+  status: ConstitutionStatus;
+  reason: string | null;
+  subject: string;
+  type: string;
+  subject_profile: ConstitutionalSubjectProfile;
+  legal_effect?: LegalEffect;
+  norms?: string[];
+  instruments?: ConstitutionalInstrument[];
+  governance?: ConstitutionalGovernance;
+  execution?: ConstitutionalExecution;
+  constitutional_ai?: ConstitutionalAI;
+}
+
+export interface LintReport {
+  tool: '@ixo/domain.md';
+  toolVersion: string;
+  specVersion: string;
+  sourceName: string;
+  mode: DomainMode | null;
+  profile: ConformanceProfile | null;
+  status: 'static-pass' | 'fail';
+  ok: boolean;
+  summary: FindingSummary;
+  findings: Finding[];
+  externalChecksRequired: ExternalCheck[];
+  document?: DomainDocument;
+}
+
+export type ChangeClassification = 'security-sensitive' | 'operational' | 'narrative';
+
+export interface DomainChange {
+  path: string;
+  classification: ChangeClassification;
+  before?: unknown;
+  after?: unknown;
+}
+
+export interface DiffOptions {
+  failOn?: 'regression' | 'review';
+}
+
+export interface DiffReport {
+  before: FindingSummary;
+  after: FindingSummary;
+  changes: DomainChange[];
+  conformanceRegression: boolean;
+  requiresReview: boolean;
+  regression: boolean;
+}
+
+export interface ExportOptions {
+  format: 'json' | 'sarif';
+  sourceName?: string;
+}

package/src/workers.ts

@@ -0,0 +1,6 @@
+/** Workers nodejs_compat entry: no filesystem, network resolvers or dynamic compilation. */
+export { lint } from './lint.js';
+export { parseDomain } from './parser.js';
+export * from './capsule/index.js';
+export { SPEC_VERSION, PACKAGE_VERSION } from './constants.js';
+export type * from './types.js';