@nobulex/sdk 0.1.0

package/dist/benchmarks.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { runBenchmarkSuite, benchmark, PERFORMANCE_SLAS, formatBenchmarkResults } from './benchmarks.js';
+describe('Performance SLAs', () => {
+    it('all SLA targets are met', async () => {
+        const results = await runBenchmarkSuite();
+        console.log(formatBenchmarkResults(results));
+        expect(results.allPassed).toBe(true);
+    }, 60_000); // 60s timeout for benchmarks
+    it('PERFORMANCE_SLAS covers all critical operations', () => {
+        const required = [
+            'crypto.generateKeyPair',
+            'crypto.sign',
+            'crypto.verify',
+            'ccl.parse',
+            'ccl.evaluate',
+            'covenant.build',
+            'covenant.verify',
+        ];
+        for (const op of required) {
+            expect(PERFORMANCE_SLAS).toHaveProperty(op);
+        }
+    });
+    it('benchmark utility computes correct percentiles', async () => {
+        const result = await benchmark('test.noop', () => { }, 100);
+        expect(result.iterations).toBe(100);
+        expect(result.p50).toBeLessThanOrEqual(result.p95);
+        expect(result.p95).toBeLessThanOrEqual(result.p99);
+        expect(result.min).toBeLessThanOrEqual(result.p50);
+        expect(result.max).toBeGreaterThanOrEqual(result.p99);
+    });
+    it('benchmark result has correct structure', async () => {
+        const result = await benchmark('test.structure', () => { }, 50);
+        expect(result).toHaveProperty('name', 'test.structure');
+        expect(result).toHaveProperty('iterations', 50);
+        expect(typeof result.p50).toBe('number');
+        expect(typeof result.p95).toBe('number');
+        expect(typeof result.p99).toBe('number');
+        expect(typeof result.min).toBe('number');
+        expect(typeof result.max).toBe('number');
+        expect(typeof result.mean).toBe('number');
+        expect(typeof result.slaTarget).toBe('number');
+        expect(typeof result.slaPassed).toBe('boolean');
+    });
+    it('formatBenchmarkResults produces readable output', async () => {
+        const result = await benchmark('test.format', () => { }, 50);
+        const suiteResult = {
+            results: [result],
+            allPassed: true,
+            totalDuration: 100,
+            timestamp: new Date().toISOString(),
+        };
+        const output = formatBenchmarkResults(suiteResult);
+        expect(output).toContain('test.format');
+        expect(output).toContain('PASS');
+        expect(output).toContain('Stele Performance Benchmark Suite');
+    });
+    it('PERFORMANCE_SLAS has all 13 targets', () => {
+        const keys = Object.keys(PERFORMANCE_SLAS);
+        expect(keys.length).toBe(13);
+    });
+    it('all SLA targets have required fields', () => {
+        for (const [name, sla] of Object.entries(PERFORMANCE_SLAS)) {
+            expect(typeof sla.p99).toBe('number');
+            expect(sla.unit).toBe('ms');
+            expect(typeof sla.description).toBe('string');
+            expect(sla.description.length).toBeGreaterThan(0);
+            expect(sla.p99).toBeGreaterThan(0);
+        }
+    });
+});
+//# sourceMappingURL=benchmarks.test.js.map

package/dist/benchmarks.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmarks.test.js","sourceRoot":"","sources":["../src/benchmarks.test.ts"],"names":[],"mappings":"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"}

package/dist/conformance.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Stele Protocol Conformance Suite
+ *
+ * Provides test vectors and validation functions for any implementation
+ * of the Stele protocol. Implementations that pass all conformance checks
+ * are considered spec-compliant.
+ *
+ * Like the W3C Acid Tests for browsers or TLS conformance suites --
+ * a standardized set of test vectors that any Stele implementation must pass.
+ *
+ * This module is self-contained at runtime: it uses the provided
+ * {@link ConformanceTarget} interface to generate keys and test documents.
+ * Type imports from @stele packages are used only for interface definitions.
+ *
+ * @packageDocumentation
+ */
+import type { CovenantDocument, CovenantBuilderOptions, VerificationResult } from '@nobulex/core';
+import type { CCLDocument, EvaluationResult as CCLEvaluationResult } from '@nobulex/ccl';
+import type { KeyPair } from '@nobulex/crypto';
+/** Aggregate result from running the full conformance suite. */
+export interface ConformanceResult {
+    /** True when every check passed. */
+    passed: boolean;
+    /** Total number of individual checks that were executed. */
+    total: number;
+    /** Details for every check that failed. */
+    failures: ConformanceFailure[];
+    /** Wall-clock duration in milliseconds. */
+    duration: number;
+}
+/** A single conformance check that did not pass. */
+export interface ConformanceFailure {
+    /** Short identifier for the check (e.g. `"ed25519-roundtrip"`). */
+    test: string;
+    /** Category the check belongs to (e.g. `"crypto"`, `"ccl"`). */
+    category: string;
+    /** The value the check expected. */
+    expected: unknown;
+    /** The value the implementation actually produced. */
+    actual: unknown;
+    /** Human-readable explanation of the failure. */
+    message: string;
+}
+/**
+ * Functions that the implementation under test must provide.
+ *
+ * Any Stele-compatible implementation can be tested by wiring up these
+ * functions and passing the resulting object to {@link runConformanceSuite}.
+ */
+export interface ConformanceTarget {
+    /** Build a signed covenant document from builder options. */
+    buildCovenant: (options: CovenantBuilderOptions) => Promise<CovenantDocument>;
+    /** Verify a covenant document. Returns `{ valid, checks }`. */
+    verifyCovenant: (doc: CovenantDocument) => Promise<VerificationResult>;
+    /** Evaluate an action/resource against a covenant's CCL constraints. */
+    evaluateAction: (doc: CovenantDocument, action: string, resource: string, context?: Record<string, unknown>) => Promise<CCLEvaluationResult>;
+    /** Generate an Ed25519 key pair. Returns `{ privateKey, publicKey, publicKeyHex }`. */
+    generateKeyPair: () => Promise<KeyPair>;
+    /** Sign a message with an Ed25519 private key. */
+    sign: (message: Uint8Array, privateKey: Uint8Array) => Promise<Uint8Array>;
+    /** Verify an Ed25519 signature. */
+    verify: (message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array) => Promise<boolean>;
+    /** SHA-256 hash returning a lowercase hex string. */
+    sha256: (data: Uint8Array) => Promise<string> | string;
+    /** Parse CCL source text into a CCLDocument. */
+    parseCCL: (source: string) => CCLDocument;
+}
+/** Result from a single conformance category. */
+interface CategoryResult {
+    failures: ConformanceFailure[];
+    total: number;
+}
+/**
+ * Verify that the target's cryptographic primitives conform to spec.
+ *
+ * Checks:
+ * - Ed25519 sign/verify round-trip
+ * - SHA-256 known-answer tests (NIST vectors)
+ * - Signature verification rejects tampered messages
+ * - Different keys produce different signatures
+ * - Wrong public key rejects valid signature
+ */
+export declare function cryptoConformance(target: ConformanceTarget): Promise<CategoryResult>;
+/**
+ * Verify that the target's CCL parser and evaluator conform to spec.
+ *
+ * Checks:
+ * - `permit read on '/data'` permits read on /data
+ * - `deny write on '/system/**'` denies write on /system/config
+ * - Default deny: no matching rule results in denied
+ * - Deny-wins: permit + deny on same resource results in denied
+ * - Wildcards: `**` matches nested paths
+ * - Rate limits parse correctly
+ * - Conditions evaluate correctly
+ * - Exact resource matching: `/secrets` does NOT match `/secrets/key`
+ */
+export declare function cclConformance(target: ConformanceTarget): Promise<CategoryResult>;
+/**
+ * Verify that the target's covenant build/verify lifecycle conforms to spec.
+ *
+ * Checks:
+ * - Build -> verify round-trip
+ * - Tampered covenant fails verification
+ * - Expired covenant detected
+ * - ID integrity check (id matches content hash)
+ * - Constraints must be valid CCL
+ * - Nonce must be present
+ * - Signature is a hex string of correct length
+ */
+export declare function covenantConformance(target: ConformanceTarget): Promise<CategoryResult>;
+/**
+ * Verify cross-implementation interoperability.
+ *
+ * Checks:
+ * - Canonical JSON test vectors (JCS compatibility)
+ * - JSON serialize/deserialize round-trip
+ * - Document ID matches reference canonical form hash
+ * - ID format (64-char lowercase hex)
+ * - Protocol version is "1.0"
+ * - Nonce format (64-char hex)
+ */
+export declare function interopConformance(target: ConformanceTarget): Promise<CategoryResult>;
+/**
+ * Run the complete Stele Protocol Conformance Suite.
+ *
+ * Executes all four categories (crypto, CCL, covenant, interop) and
+ * aggregates the results. An implementation that returns
+ * `result.passed === true` is considered spec-compliant.
+ *
+ * @param target - The implementation under test.
+ * @returns Aggregate conformance result.
+ *
+ * @example
+ * ```typescript
+ * import { runConformanceSuite } from '@nobulex/sdk/conformance';
+ * import { buildCovenant, verifyCovenant } from '@nobulex/core';
+ * import { generateKeyPair, sign, verify, sha256 } from '@nobulex/crypto';
+ * import { parse, evaluate } from '@nobulex/ccl';
+ *
+ * const result = await runConformanceSuite({
+ *   buildCovenant,
+ *   verifyCovenant,
+ *   evaluateAction: async (doc, action, resource, ctx) => {
+ *     const cclDoc = parse(doc.constraints);
+ *     return evaluate(cclDoc, action, resource, ctx);
+ *   },
+ *   generateKeyPair,
+ *   sign: async (msg, key) => sign(msg, key),
+ *   verify: async (msg, sig, key) => verify(msg, sig, key),
+ *   sha256: (data) => sha256(data),
+ *   parseCCL: parse,
+ * });
+ *
+ * console.log(result.passed);  // true
+ * console.log(result.total);   // number of checks run
+ * ```
+ */
+export declare function runConformanceSuite(target: ConformanceTarget): Promise<ConformanceResult>;
+export {};
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"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"}