domainforge 0.13.0

package/docs/reference/security-model.md

@@ -0,0 +1,74 @@
+# Security Model
+
+This document describes the DomainForge security model, focusing on how untrusted input is handled.
+
+## Threat Model: Untrusted .sea Input
+
+DomainForge processes `.sea` DSL files that may originate from untrusted sources. The primary threat vectors are:
+
+- **Malformed input** designed to trigger panics or resource exhaustion in the parser
+- **Path traversal** via import paths or namespace declarations
+- **Archive extraction** exploits when unpacking semantic packs
+- **Injection** of executable content through DSL constructs
+
+The parser is the primary attack surface. It must handle arbitrary input without panicking, exhausting memory, or executing external processes.
+
+## Parser Limits
+
+The Pest-based parser processes input through a PEG grammar. Known behaviors:
+
+- **Deeply nested expressions**: Excessive nesting (hundreds of levels) may hit recursion limits. The parser returns a `ParseError` rather than panicking.
+- **Large input**: Files with hundreds of thousands of declarations are accepted. Memory usage scales linearly with input size.
+- **Null bytes**: Input containing null bytes is handled gracefully and produces a parse error.
+- **Long strings**: Individual string literals up to at least 1 MB are processed without panicking.
+
+Test coverage for these limits lives in `domainforge-core/tests/parser_resource_limits_tests.rs`.
+
+## Namespace and Import Path Restrictions
+
+The module resolver enforces the following restrictions:
+
+- **No path separators** in namespace declarations. Forward slashes (`/`) and backslashes (`\`) are rejected.
+- **No path traversal** sequences (`..`) in namespace or import paths.
+- **No absolute paths** in namespace declarations.
+- **Circular imports** are detected and reported as `E505: CircularDependency` with the full cycle path.
+
+These checks are implemented in `domainforge_core::projection::protobuf::validate_proto_package_namespace` and `domainforge_core::module::resolver::ModuleResolver`.
+
+## Safe Archive Extraction
+
+When extracting semantic packs (`.sea-pack` archives), the following protections apply:
+
+- **Path traversal prevention**: Archive entries with paths containing `..` or absolute paths are rejected.
+- **Size limits**: Archive entries exceeding configured size thresholds are rejected before extraction.
+- **Symlink handling**: Symlinks within archives are not followed during extraction.
+
+## No Process Execution from Model Content
+
+DomainForge does **not** execute external processes based on the content of `.sea` files. Specifically:
+
+- DSL declarations (Entity, Resource, Flow, Policy, etc.) are data declarations only
+- Annotations and metadata are parsed as structured data, never evaluated as code
+- The `export` keyword controls visibility within the DSL namespace system
+- No `eval()`, `system()`, or subprocess invocation exists in the parser or graph construction pipeline
+- CLI commands operate on files and produce structured output (JSON, Turtle, Protobuf) without interpreting DSL content as executable instructions
+
+## Cargo Supply Chain Security
+
+Dependency auditing is enforced through:
+
+- **cargo-audit**: Scans for known vulnerabilities in dependencies
+- **cargo-deny**: Enforces license allowlists, bans duplicate versions, and denies wildcard dependencies
+- **Configuration**: `deny.toml` at the workspace root defines the policy
+
+Run `just audit` to check dependencies locally, or `just enterprise-verify` for the full release verification pipeline.
+
+## Release Workflow Linting
+
+Three Python scripts validate CI/CD workflow files for security issues:
+
+| Script | Checks |
+|--------|--------|
+| `scripts/lint_release_workflows.py` | Unfrozen npm installs, curl without checksums, continue-on-error on publish |
+| `scripts/lint_release_security.py` | curl pipe to shell, publish failure masking, token exposure during builds |
+| `scripts/lint_workflow_gates.py` | Artifact upload jobs gated by create-release, dependabot empty-check handling |

package/docs/reference/typescript-api.md

@@ -0,0 +1,508 @@
+# @godspeedai/domainforge
+
+TypeScript/Node.js bindings for the SEA (Semantic Enterprise Architecture) DSL.
+
+## Installation
+
+```bash
+# From source (npm package coming soon)
+git clone https://github.com/GodSpeedAI/DomainForge.git
+cd DomainForge
+npm install
+npm run build
+
+# The build produces native .node bindings
+```
+
+## Quick Start
+
+```typescript
+import { Graph, Entity, Resource, Flow } from "@godspeedai/domainforge";
+
+// Create a graph programmatically
+const graph = new Graph();
+
+// Constructor patterns - new() for default namespace, newWithNamespace() for explicit
+const warehouse = Entity.new("Warehouse"); // Default namespace
+const factory = Entity.newWithNamespace("Factory", "manufacturing");
+
+// Namespace is always a string (not undefined), defaults to "default"
+console.log(warehouse.namespace()); // "default"
+console.log(factory.namespace()); // "manufacturing"
+
+const cameras = Resource.new("Cameras", "units");
+
+graph.addEntity(warehouse);
+graph.addEntity(factory);
+graph.addResource(cameras);
+
+// Flow constructor takes ConceptId values - clone before passing
+const flow = Flow.new(
+  cameras.id().clone(),
+  warehouse.id().clone(),
+  factory.id().clone(),
+  100
+);
+graph.addFlow(flow);
+
+console.log(`Graph has ${graph.entityCount()} entities`);
+console.log(`Graph has ${graph.flowCount()} flows`);
+```
+
+## Parsing SEA DSL
+
+```typescript
+import { Graph } from "@godspeedai/domainforge";
+
+// Supports multiline strings with """ syntax
+const source = `
+  Entity "Warehouse" in logistics
+  Entity """Multi-line
+  Factory Name""" in manufacturing
+  Resource "Cameras" units
+  Flow "Cameras" from "Warehouse" to "Multi-line\\nFactory Name" quantity 100
+`;
+
+const graph = Graph.parse(source);
+
+console.log(`Parsed ${graph.entityCount()} entities`);
+console.log(`Parsed ${graph.flowCount()} flows`);
+```
+
+### Error Handling
+
+`Graph.parse(source: string)` may throw an `Error` on invalid input. The binding typically surfaces syntax issues as a standard `Error` with a message that includes parser details (line/column); some runtimes may implement a specific `ParseError` subclass. Callers should wrap parsing in a try/catch and handle errors accordingly:
+
+```ts
+try {
+  const g = Graph.parse(source);
+} catch (e) {
+  // `e` typically includes a message and a line/column in the text
+  console.error("Failed to parse", e);
+}
+```
+
+## Formatting Source Code
+
+```typescript
+import { formatSource, checkFormat } from "@godspeedai/domainforge";
+
+// Format SEA-DSL source with default settings
+const source = 'Entity   "Foo"  in    bar';
+const formatted = formatSource(source);
+console.log(formatted); // Entity "Foo" in bar
+
+// Format with custom options
+const formatted2 = formatSource(source, {
+  indentWidth: 2,
+  useTabs: false,
+  preserveComments: true,
+  sortImports: true,
+});
+
+// Check if source is already formatted
+const isFormatted = checkFormat(source);
+console.log(isFormatted); // false
+
+// Check with formatted content
+const isFormatted2 = checkFormat('Entity "Foo" in bar\n');
+console.log(isFormatted2); // true
+```
+
+## API Reference
+
+### Formatter Functions
+
+```typescript
+// Format SEA-DSL source code
+function formatSource(source: string, options?: FormatOptions): string;
+
+// Check if source is already formatted
+function checkFormat(source: string, options?: FormatOptions): boolean;
+
+interface FormatOptions {
+  indentWidth?: number; // Default: 4
+  useTabs?: boolean; // Default: false
+  preserveComments?: boolean; // Default: true
+  sortImports?: boolean; // Default: true
+}
+```
+
+### Entity
+
+```typescript
+class Entity {
+  static new(name: string): Entity; // Default namespace
+  static newWithNamespace(name: string, namespace: string): Entity; // Explicit namespace
+
+  id(): ConceptId;
+  name(): string;
+  namespace(): string; // Always returns string, never undefined (defaults to "default")
+  setAttribute(key: string, value: any): void;
+  getAttribute(key: string): any;
+}
+```
+
+### Resource
+
+```typescript
+class Resource {
+  // Constructor patterns (November 2025)
+  static new(name: string, unit: string): Resource; // Default namespace
+  static newWithNamespace(
+    name: string,
+    unit: string,
+    namespace: string
+  ): Resource;
+
+  id(): ConceptId;
+  name(): string;
+  unit(): string;
+  namespace(): string; // Always returns string (defaults to "default")
+  setAttribute(key: string, value: any): void;
+  getAttribute(key: string): any;
+}
+```
+
+### Flow
+
+```typescript
+class Flow {
+  // Constructor takes ConceptId values (not references) - clone before passing
+  static new(
+    resourceId: ConceptId,
+    fromId: ConceptId,
+    toId: ConceptId,
+    quantity: number
+  ): Flow;
+
+  id(): ConceptId;
+  resourceId(): ConceptId;
+  fromId(): ConceptId;
+  toId(): ConceptId;
+  quantity(): number;
+  namespace(): string;
+  setAttribute(key: string, value: any): void;
+  getAttribute(key: string): any;
+}
+```
+
+### Instance
+
+```typescript
+class Instance {
+  static new(resourceId: ConceptId, entityId: ConceptId): Instance; // Default namespace
+  static newWithNamespace(
+    resourceId: ConceptId,
+    entityId: ConceptId,
+    namespace: string
+  ): Instance;
+
+  id(): ConceptId;
+  resourceId(): ConceptId;
+  entityId(): ConceptId;
+  namespace(): string; // Always returns string (defaults to "default")
+  setAttribute(key: string, value: any): void;
+  getAttribute(key: string): any;
+}
+```
+
+### Graph
+
+```typescript
+class Graph {
+  constructor();
+
+  // Add primitives (validates referential integrity)
+  addEntity(entity: Entity): void;
+  addResource(resource: Resource): void;
+  addFlow(flow: Flow): void;  // Throws if Entity/Resource references invalid
+  addInstance(instance: Instance): void;
+
+  // Counts
+  entityCount(): number;
+  resourceCount(): number;
+  flowCount(): number;
+  instanceCount(): number;
+
+  // Lookup by ID
+  hasEntity(id: ConceptId): boolean;
+  getEntity(id: ConceptId): Entity | null;
+  getResource(id: ConceptId): Resource | null;
+  getFlow(id: ConceptId): Flow | null;
+  getInstance(id: ConceptId): Instance | null;
+
+  // Lookup by name
+  findEntityByName(name: string): ConceptId | null;
+  findResourceByName(name: string): ConceptId | null;
+
+  // Flow queries
+  flowsFrom(entityId: ConceptId): Flow[];
+  flowsTo(entityId: ConceptId): Flow[];
+
+  // Get all (IndexMap ensures deterministic iteration order)
+  allEntities(): Entity[];
+  allResources(): Resource[];
+  allFlows(): Flow[];
+  allInstances(): Instance[];
+
+  // Parsing (supports multiline strings with """)
+  static parse(source: string): Graph;
+
+  // CALM integration (architecture-as-code)
+  exportCalm(): string;  // Returns CALM JSON string
+  static importCalm(json: string): Graph;  // Import from CALM JSON
+}
+
+`Graph.importCalm` will throw if the JSON is invalid or violates schema constraints; callers should also wrap `importCalm` in try/catch and inspect error messages for details.
+```
+
+### Expression API (December 2025)
+
+```typescript
+import { Expression, BinaryOp } from "@godspeedai/domainforge";
+
+// Factory methods
+const expr = Expression.binary(
+  BinaryOp.And,
+  Expression.variable("b"),
+  Expression.variable("a")
+);
+
+// Normalization
+const normalized = expr.normalize();
+console.log(normalized.toStringRepr()); // "(a AND b)"
+console.log(normalized.stableHashHex()); // Stable hash
+```
+
+### Expression and BinaryOp
+
+```typescript
+enum BinaryOp {
+  And,
+  Or,
+  Equal,
+  NotEqual,
+  GreaterThan,
+  LessThan,
+  GreaterThanOrEqual,
+  LessThanOrEqual,
+  Plus,
+  Minus,
+  Multiply,
+  Divide,
+  Contains,
+  StartsWith,
+  EndsWith,
+  Matches,
+  HasRole,
+  Before,
+  After,
+  During,
+}
+
+class Expression {
+  // Factories
+  static literal(valueJson: string): Expression;
+  static literalBool(value: boolean): Expression;
+  static literalNumber(value: number): Expression;
+  static literalString(value: string): Expression;
+  static variable(name: string): Expression;
+  static binary(op: BinaryOp, left: Expression, right: Expression): Expression;
+
+  // Methods
+  normalize(): NormalizedExpression;
+  isEquivalent(other: Expression): boolean;
+  toStringRepr(): string;
+  equals(other: Expression): boolean;
+}
+
+class NormalizedExpression {
+  stableHash(): string;
+  stableHashHex(): string;
+  innerExpression(): Expression;
+  toStringRepr(): string;
+  equals(other: NormalizedExpression): boolean;
+}
+```
+
+### NamespaceRegistry (Workspace)
+
+```typescript
+import { NamespaceRegistry } from "@godspeedai/domainforge";
+
+// Load a registry by path to the file
+const reg = NamespaceRegistry.from_file("./.sea-registry.toml");
+
+// Expand files and get bindings
+const files = reg.resolve_files(); // or reg.resolve_files(true) to fail on ambiguity via the failOnAmbiguity flag
+for (const f of files) {
+  console.log(f.path, "=>", f.namespace);
+}
+
+// Query namespace for a single file
+const ns = reg.namespace_for("/path/to/file.sea"); // or pass true as the failOnAmbiguity flag to error on ambiguous matches
+console.log("Namespace:", ns);
+```
+
+## Advanced Usage
+
+### Working with Attributes
+
+```typescript
+// Use new() for default namespace
+const entity = Entity.new("Warehouse");
+entity.setAttribute("capacity", JSON.stringify(10000));
+entity.setAttribute("location", JSON.stringify({ lat: 40.7128, lng: -74.006 }));
+
+const capacity = JSON.parse(entity.getAttribute("capacity")!); // 10000
+const location = JSON.parse(entity.getAttribute("location")!); // { lat: 40.7128, lng: -74.0060 }
+
+// Namespace is always present (not undefined)
+console.log(entity.namespace()); // "default"
+```
+
+### Querying Flow Networks
+
+```typescript
+const graph = Graph.parse(`
+  Entity "Supplier"
+  Entity "Warehouse"
+  Entity "Retailer"
+  Resource "Products" units
+  Flow "Products" from "Supplier" to "Warehouse" quantity 1000
+  Flow "Products" from "Warehouse" to "Retailer" quantity 800
+`);
+
+const warehouseId = graph.findEntityByName("Warehouse");
+const inboundFlows = graph.flowsTo(warehouseId!);
+const outboundFlows = graph.flowsFrom(warehouseId!);
+
+console.log(`Warehouse receives ${inboundFlows.length} flows`);
+console.log(`Warehouse sends ${outboundFlows.length} flows`);
+```
+
+## Building from Source
+
+```bash
+# Install dependencies
+npm install
+
+# Build the native module
+npm run build
+
+# Run tests
+npm test
+```
+
+## Platform Support
+
+Pre-built binaries are available for:
+
+- Linux x64
+- macOS ARM64 (Apple Silicon)
+- Windows x64
+
+Build from source for other platforms using `npm run build`.
+
+## Semantic Pack API
+
+The `@godspeedai/domainforge` module exposes semantic pack enums and functions for building, validating, signing, and inspecting packs programmatically.
+
+### Enums
+
+```typescript
+import {
+  SemanticTruth,              // Valid = 0, Invalid = 1, Unknown = 2
+  DiagnosticSeverity,         // Error = 0, Warning = 1, Info = 2, Hint = 3
+  ValidationMode,             // Off = 0, Warn = 1, Strict = 2
+  ApprovalState,              // Candidate = 0, Approved = 1, Rejected = 2
+  SignatureState,             // Unsigned = 0, Signed = 1, InvalidSignature = 2
+  ConceptStatus,              // Active = 0, Proposed = 1, Deprecated = 2, Rejected = 3, ExternalOnly = 4
+  ConceptKind,                // Entity = 0, Resource = 1, Role = 2, Flow = 3, Policy = 4, Metric = 5, Dimension = 6, Unit = 7, External = 8
+  AliasStatus,                // Approved = 0, Deprecated = 1, Ambiguous = 2, Blocked = 3
+  SemanticValidationStatus,   // Passed = 0, Failed = 1, Unknown = 2, Blocked = 3
+} from "@godspeedai/domainforge";
+```
+
+### Functions
+
+#### semanticPackBuild
+
+Build a semantic pack from input JSON. Returns a JSON string with `pack`, `pack_content_hash`, `meaning_fingerprint`, `pre_pack_diagnostics`, and `build_warnings`.
+
+```typescript
+const result = semanticPackBuild(inputJson);
+const { pack, pack_content_hash, meaning_fingerprint } = JSON.parse(result);
+```
+
+#### semanticPackValidate
+
+Validate a pack's internal consistency. Returns a JSON array of diagnostics.
+
+```typescript
+const diagnosticsJson = semanticPackValidate(packJson);
+```
+
+#### semanticPackValidateGraph
+
+Validate a source against a pack with options. Returns a JSON validation result.
+
+```typescript
+const resultJson = semanticPackValidateGraph(packJson, "source_uri", optionsJson);
+```
+
+#### semanticPackSign
+
+Sign a pack with an Ed25519 private key (PEM string). Returns the signed pack JSON.
+
+```typescript
+const signedJson = semanticPackSign(packJson, privateKeyPem);
+```
+
+#### semanticPackVerify
+
+Verify a pack's Ed25519 signature. Returns `true` if valid, throws on failure.
+
+```typescript
+const isValid: boolean = semanticPackVerify(packJson, publicKeyPem);
+```
+
+#### semanticPackDiff
+
+Compare two packs. Returns a JSON diff with entries and summary.
+
+```typescript
+const diffJson = semanticPackDiff(oldPackJson, newPackJson);
+```
+
+#### semanticPackHash
+
+Compute the content hash of a pack (excluding signature fields).
+
+```typescript
+const hash: string = semanticPackHash(packJson);
+```
+
+#### semanticNormalizeKey
+
+Normalize a term for lookup (NFC, case-fold, whitespace collapse).
+
+```typescript
+const normalized: string = semanticNormalizeKey("  Hello   World  "); // "hello world"
+```
+
+#### semanticResolveConcept
+
+Resolve a term against a pack. Returns a JSON object with `resolved_concept_id`, `semantic_truth`, `diagnostic_code`, `diagnostic_severity`, `message`, and `suggestions`.
+
+```typescript
+const resultJson = semanticResolveConcept("Supplier", packJson, optionsJson);
+const result = JSON.parse(resultJson);
+console.log(result.resolved_concept_id); // "supplier" or null
+console.log(result.semantic_truth);       // "valid", "invalid", or "unknown"
+```
+
+## License
+
+Apache-2.0