@totemsdk/manifest 0.1.0

package/dist/verify.js

@@ -0,0 +1,59 @@
+/**
+ * verifyManifest — verifies a SignedManifest without external state.
+ *
+ * Steps:
+ *   1. Recompute the canonical manifest digest.
+ *   2. Verify the WOTS signature against the stored 32-byte PKdigest
+ *      (signerPublicKey field) using wotsVerifyDigest.
+ *   3. Confirm authorAddress matches the manifest's address field.
+ *
+ * wotsVerifyDigest is used (rather than wotsVerify) because signerPublicKey
+ * stores the 32-byte WOTS PKdigest as returned by wotsKeypairFromSeed.kp.pk.
+ * The full 1088-byte key is not stored in SignedManifest to keep it compact.
+ */
+import { wotsVerifyDigest, hexToBytes } from '@totemsdk/core';
+import { manifestDigest } from './sign.js';
+function manifestAddressField(manifest) {
+    switch (manifest.type) {
+        case 'app': return manifest.authorAddress;
+        case 'capability': return manifest.agentAddress;
+        case 'dapp': return manifest.authorAddress;
+        case 'edge-service': return manifest.operatorAddress;
+        default: {
+            const _exhaustive = manifest;
+            throw new Error(`verifyManifest: unknown manifest type: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+export function verifyManifest(signed) {
+    const { manifest, signature, signerPublicKey, authorAddress } = signed;
+    let sigBytes;
+    let pkDigest;
+    try {
+        sigBytes = hexToBytes(signature);
+        pkDigest = hexToBytes(signerPublicKey);
+    }
+    catch (e) {
+        return { valid: false, reason: `hex decode failed: ${String(e)}`, signerAddress: authorAddress };
+    }
+    const digest = manifestDigest(manifest);
+    let sigValid;
+    try {
+        sigValid = wotsVerifyDigest(sigBytes, digest, pkDigest);
+    }
+    catch (e) {
+        return { valid: false, reason: `WOTS verify threw: ${String(e)}`, signerAddress: authorAddress };
+    }
+    if (!sigValid) {
+        return { valid: false, reason: 'WOTS signature invalid', signerAddress: authorAddress };
+    }
+    const expectedAddress = manifestAddressField(manifest);
+    if (authorAddress !== expectedAddress) {
+        return {
+            valid: false,
+            reason: `authorAddress mismatch: signed by '${authorAddress}' but manifest declares '${expectedAddress}'`,
+            signerAddress: authorAddress,
+        };
+    }
+    return { valid: true, signerAddress: authorAddress };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@totemsdk/manifest",
+  "version": "0.1.0",
+  "description": "Canonical signed declaration format for Totem Edge entities — apps, agent capabilities, dApps, and edge services",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@totemsdk/core": "1.0.9"
+  },
+  "peerDependencies": {
+    "@noble/hashes": ">=1.3.0 <2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@noble/hashes": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@noble/hashes": "^1.3.0",
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests"
+  }
+}

package/src/__tests__/encoding.test.ts

@@ -0,0 +1,185 @@
+/**
+ * encoding.test.ts
+ * encode → decode round-trips for all four manifest types.
+ */
+
+import { signManifest } from '../sign.js';
+import { encodeManifest, decodeManifest } from '../encoding.js';
+import { MANIFEST_VERSION, MANIFEST_TYPE_BYTE } from '../constants.js';
+import type {
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+} from '../types.js';
+
+jest.setTimeout(60_000);
+
+const TEST_SEED = new Uint8Array(32).fill(0x11);
+const KEY_INDEX = 0;
+
+let resolvedAddress: string;
+
+beforeAll(async () => {
+  const tmp = await signManifest(
+    {
+      type: 'app',
+      appId: '',
+      name: 'init',
+      version: '1.0.0',
+      authorAddress: 'MxINIT',
+      pearTopicKey: 'a'.repeat(64),
+      price: '0',
+      category: [],
+      permissions: [],
+      description: '',
+      minTotemVersion: '0.1.0',
+    } satisfies AppManifest,
+    TEST_SEED,
+    KEY_INDEX,
+  );
+  resolvedAddress = tmp.authorAddress;
+});
+
+describe('encodeManifest / decodeManifest', () => {
+  it('round-trips AppManifest and preserves manifest type', async () => {
+    const manifest: AppManifest = {
+      type: 'app',
+      appId: 'abc123',
+      name: 'My App',
+      version: '1.0.0',
+      authorAddress: resolvedAddress,
+      pearTopicKey: 'f'.repeat(64),
+      price: '0',
+      category: ['finance'],
+      permissions: ['wallet:read-balance'],
+      description: 'Test',
+      minTotemVersion: '0.1.0',
+    };
+    const signed = await signManifest(manifest, TEST_SEED, KEY_INDEX);
+    const encoded = encodeManifest(signed);
+    const decoded = decodeManifest(encoded);
+
+    expect(decoded.manifest.type).toBe('app');
+    expect(decoded.manifest.type).toBe(signed.manifest.type);
+    expect((decoded.manifest as AppManifest).name).toBe('My App');
+    expect(decoded.signature).toBe(signed.signature);
+  });
+
+  it('round-trips CapabilityManifest', async () => {
+    const manifest: CapabilityManifest = {
+      type: 'capability',
+      capabilityId: 'cap1',
+      capabilityName: 'price-oracle',
+      agentAddress: resolvedAddress,
+      agentIdentityKey: 'e'.repeat(64),
+      description: 'Price oracle',
+      inputSchema: { type: 'object' },
+      outputSchema: { type: 'object' },
+      pricePerCall: '2',
+      expiresAt: Date.now() + 3600_000,
+      tags: ['oracle'],
+    };
+    const signed = await signManifest(manifest, TEST_SEED, KEY_INDEX);
+    const encoded = encodeManifest(signed);
+    const decoded = decodeManifest(encoded);
+
+    expect(decoded.manifest.type).toBe('capability');
+    expect((decoded.manifest as CapabilityManifest).capabilityName).toBe('price-oracle');
+  });
+
+  it('round-trips DAppManifest', async () => {
+    const manifest: DAppManifest = {
+      type: 'dapp',
+      dappId: 'dapp1',
+      name: 'Swap dApp',
+      version: '2.0.0',
+      authorAddress: resolvedAddress,
+      contractHash: 'd'.repeat(64),
+      abi: [],
+      price: '5',
+      category: ['defi'],
+      description: 'A swap contract',
+    };
+    const signed = await signManifest(manifest, TEST_SEED, KEY_INDEX);
+    const encoded = encodeManifest(signed);
+    const decoded = decodeManifest(encoded);
+
+    expect(decoded.manifest.type).toBe('dapp');
+    expect((decoded.manifest as DAppManifest).name).toBe('Swap dApp');
+  });
+
+  it('round-trips EdgeServiceManifest', async () => {
+    const manifest: EdgeServiceManifest = {
+      type: 'edge-service',
+      serviceId: 'edge1',
+      name: 'DHT Relay',
+      version: '1.0.0',
+      operatorAddress: resolvedAddress,
+      serviceType: 'omnia-router',
+      description: 'Omnia routing node',
+      capabilities: ['relay'],
+      tags: ['infrastructure'],
+    };
+    const signed = await signManifest(manifest, TEST_SEED, KEY_INDEX);
+    const encoded = encodeManifest(signed);
+    const decoded = decodeManifest(encoded);
+
+    expect(decoded.manifest.type).toBe('edge-service');
+    expect((decoded.manifest as EdgeServiceManifest).serviceType).toBe('omnia-router');
+  });
+
+  it('first byte is MANIFEST_VERSION', async () => {
+    const manifest: AppManifest = {
+      type: 'app',
+      appId: '',
+      name: 'v-test',
+      version: '1.0.0',
+      authorAddress: resolvedAddress,
+      pearTopicKey: 'a'.repeat(64),
+      price: '0',
+      category: [],
+      permissions: [],
+      description: '',
+      minTotemVersion: '0.1.0',
+    };
+    const signed = await signManifest(manifest, TEST_SEED, KEY_INDEX);
+    const encoded = encodeManifest(signed);
+    expect(encoded[0]).toBe(MANIFEST_VERSION);
+  });
+
+  it('second byte is correct type discriminant', async () => {
+    const appSigned = await signManifest(
+      { type: 'app', appId: '', name: 'x', version: '1.0.0', authorAddress: resolvedAddress, pearTopicKey: 'a'.repeat(64), price: '0', category: [], permissions: [], description: '', minTotemVersion: '0.1.0' } satisfies AppManifest,
+      TEST_SEED, KEY_INDEX,
+    );
+    expect(encodeManifest(appSigned)[1]).toBe(MANIFEST_TYPE_BYTE.app);
+
+    const capSigned = await signManifest(
+      { type: 'capability', capabilityId: '', capabilityName: 'x', agentAddress: resolvedAddress, agentIdentityKey: 'e'.repeat(64), description: '', inputSchema: {}, outputSchema: {}, pricePerCall: '1', expiresAt: 0, tags: [] } satisfies CapabilityManifest,
+      TEST_SEED, KEY_INDEX,
+    );
+    expect(encodeManifest(capSigned)[1]).toBe(MANIFEST_TYPE_BYTE.capability);
+
+    const edgeSigned = await signManifest(
+      { type: 'edge-service', serviceId: '', name: 'x', version: '1.0.0', operatorAddress: resolvedAddress, serviceType: 'sensor', description: '', capabilities: [], tags: [] } satisfies EdgeServiceManifest,
+      TEST_SEED, KEY_INDEX,
+    );
+    expect(encodeManifest(edgeSigned)[1]).toBe(MANIFEST_TYPE_BYTE['edge-service']);
+  });
+
+  it('throws on unknown type discriminant byte', () => {
+    const bad = new Uint8Array([1, 0xff, 0, 0, 0, 5, 104, 101, 108, 108, 111]);
+    expect(() => decodeManifest(bad)).toThrow(/unknown type discriminant/);
+  });
+
+  it('throws on buffer too short', () => {
+    expect(() => decodeManifest(new Uint8Array([1, 1, 0, 0]))).toThrow(/too short/);
+  });
+
+  it('throws on MANIFEST_VERSION mismatch', () => {
+    const bad = new Uint8Array(10).fill(0);
+    bad[0] = 255;
+    expect(() => decodeManifest(bad)).toThrow(/unsupported MANIFEST_VERSION/);
+  });
+});

package/src/__tests__/guards.test.ts

@@ -0,0 +1,140 @@
+/**
+ * guards.test.ts
+ * Type guard tests for all four manifest kinds.
+ * Guards must work on both raw manifests and SignedManifest wrappers.
+ */
+
+import {
+  isAppManifest,
+  isCapabilityManifest,
+  isDAppManifest,
+  isEdgeServiceManifest,
+} from '../guards.js';
+import type {
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+  SignedManifest,
+} from '../types.js';
+
+const APP: AppManifest = {
+  type: 'app',
+  appId: '',
+  name: 'Test',
+  version: '1.0.0',
+  authorAddress: 'MxAPP',
+  pearTopicKey: 'a'.repeat(64),
+  price: '0',
+  category: [],
+  permissions: [],
+  description: '',
+  minTotemVersion: '0.1.0',
+};
+
+const CAP: CapabilityManifest = {
+  type: 'capability',
+  capabilityId: '',
+  capabilityName: 'x',
+  agentAddress: 'MxCAP',
+  agentIdentityKey: 'b'.repeat(64),
+  description: '',
+  inputSchema: {},
+  outputSchema: {},
+  pricePerCall: '1',
+  expiresAt: 0,
+  tags: [],
+};
+
+const DAPP: DAppManifest = {
+  type: 'dapp',
+  dappId: '',
+  name: 'x',
+  version: '1.0.0',
+  authorAddress: 'MxDAPP',
+  contractHash: 'c'.repeat(64),
+  abi: [],
+  price: '0',
+  category: [],
+  description: '',
+};
+
+const EDGE: EdgeServiceManifest = {
+  type: 'edge-service',
+  serviceId: '',
+  name: 'x',
+  version: '1.0.0',
+  operatorAddress: 'MxEDGE',
+  serviceType: 'lookup-provider',
+  description: '',
+  capabilities: [],
+  tags: [],
+};
+
+function mockSigned<T extends { type: string }>(manifest: T): SignedManifest<T extends AppManifest ? AppManifest : T extends CapabilityManifest ? CapabilityManifest : T extends DAppManifest ? DAppManifest : EdgeServiceManifest> {
+  return {
+    manifest: manifest as any,
+    authorAddress: 'MxSIGNER',
+    signerPublicKey: 'aa'.repeat(544),
+    signedAt: Date.now(),
+    signature: 'bb'.repeat(100),
+  };
+}
+
+describe('isAppManifest', () => {
+  it('returns true for raw AppManifest', () => expect(isAppManifest(APP)).toBe(true));
+  it('returns true for SignedManifest<AppManifest>', () => expect(isAppManifest(mockSigned(APP))).toBe(true));
+  it('returns false for CapabilityManifest', () => expect(isAppManifest(CAP)).toBe(false));
+  it('returns false for DAppManifest', () => expect(isAppManifest(DAPP)).toBe(false));
+  it('returns false for EdgeServiceManifest', () => expect(isAppManifest(EDGE)).toBe(false));
+  it('returns false for null', () => expect(isAppManifest(null)).toBe(false));
+  it('returns false for undefined', () => expect(isAppManifest(undefined)).toBe(false));
+  it('returns false for SignedManifest<CapabilityManifest>', () => expect(isAppManifest(mockSigned(CAP))).toBe(false));
+});
+
+describe('isCapabilityManifest', () => {
+  it('returns true for raw CapabilityManifest', () => expect(isCapabilityManifest(CAP)).toBe(true));
+  it('returns true for SignedManifest<CapabilityManifest>', () => expect(isCapabilityManifest(mockSigned(CAP))).toBe(true));
+  it('returns false for AppManifest', () => expect(isCapabilityManifest(APP)).toBe(false));
+  it('returns false for DAppManifest', () => expect(isCapabilityManifest(DAPP)).toBe(false));
+  it('returns false for EdgeServiceManifest', () => expect(isCapabilityManifest(EDGE)).toBe(false));
+  it('returns false for null', () => expect(isCapabilityManifest(null)).toBe(false));
+});
+
+describe('isDAppManifest', () => {
+  it('returns true for raw DAppManifest', () => expect(isDAppManifest(DAPP)).toBe(true));
+  it('returns true for SignedManifest<DAppManifest>', () => expect(isDAppManifest(mockSigned(DAPP))).toBe(true));
+  it('returns false for AppManifest', () => expect(isDAppManifest(APP)).toBe(false));
+  it('returns false for CapabilityManifest', () => expect(isDAppManifest(CAP)).toBe(false));
+  it('returns false for EdgeServiceManifest', () => expect(isDAppManifest(EDGE)).toBe(false));
+  it('returns false for null', () => expect(isDAppManifest(null)).toBe(false));
+});
+
+describe('isEdgeServiceManifest', () => {
+  it('returns true for raw EdgeServiceManifest', () => expect(isEdgeServiceManifest(EDGE)).toBe(true));
+  it('returns true for SignedManifest<EdgeServiceManifest>', () => expect(isEdgeServiceManifest(mockSigned(EDGE))).toBe(true));
+  it('returns false for AppManifest', () => expect(isEdgeServiceManifest(APP)).toBe(false));
+  it('returns false for CapabilityManifest', () => expect(isEdgeServiceManifest(CAP)).toBe(false));
+  it('returns false for DAppManifest', () => expect(isEdgeServiceManifest(DAPP)).toBe(false));
+  it('returns false for null', () => expect(isEdgeServiceManifest(null)).toBe(false));
+});
+
+describe('cross-type guard correctness', () => {
+  const allManifests = [APP, CAP, DAPP, EDGE];
+  const guards = [isAppManifest, isCapabilityManifest, isDAppManifest, isEdgeServiceManifest];
+
+  it('each manifest is identified by exactly one guard', () => {
+    for (const m of allManifests) {
+      const trueCount = guards.filter(g => g(m)).length;
+      expect(trueCount).toBe(1);
+    }
+  });
+
+  it('each signed manifest is identified by exactly one guard', () => {
+    for (const m of allManifests) {
+      const signed = mockSigned(m);
+      const trueCount = guards.filter(g => g(signed)).length;
+      expect(trueCount).toBe(1);
+    }
+  });
+});

package/src/__tests__/id.test.ts

@@ -0,0 +1,143 @@
+/**
+ * id.test.ts
+ * Stable IDs: same inputs → same ID; version change → same ID; key field change → different ID.
+ */
+
+import { computeManifestId } from '../id.js';
+import type {
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+} from '../types.js';
+
+const APP: AppManifest = {
+  type: 'app',
+  appId: '',
+  name: 'Test App',
+  version: '1.0.0',
+  authorAddress: 'MxAUTHOR1111',
+  pearTopicKey: 'aaaa1111',
+  price: '0',
+  category: ['finance'],
+  permissions: ['wallet:read-balance'],
+  description: 'Test',
+  minTotemVersion: '0.1.0',
+};
+
+const CAP: CapabilityManifest = {
+  type: 'capability',
+  capabilityId: '',
+  capabilityName: 'invoice-translate',
+  agentAddress: 'MxAGENT2222',
+  agentIdentityKey: 'bbbb2222',
+  description: 'Translates',
+  inputSchema: {},
+  outputSchema: {},
+  pricePerCall: '1',
+  expiresAt: 9999,
+  tags: [],
+};
+
+const DAPP: DAppManifest = {
+  type: 'dapp',
+  dappId: '',
+  name: 'Swap',
+  version: '1.0.0',
+  authorAddress: 'MxAUTHOR3333',
+  contractHash: 'cccc3333',
+  abi: [],
+  price: '0',
+  category: [],
+  description: '',
+};
+
+const EDGE: EdgeServiceManifest = {
+  type: 'edge-service',
+  serviceId: '',
+  name: 'My Sensor',
+  version: '1.0.0',
+  operatorAddress: 'MxOPERATOR4444',
+  serviceType: 'sensor',
+  description: '',
+  capabilities: [],
+  tags: [],
+};
+
+describe('computeManifestId — stable IDs', () => {
+  it('returns the same ID for identical AppManifest inputs', () => {
+    expect(computeManifestId(APP)).toBe(computeManifestId({ ...APP }));
+  });
+
+  it('AppManifest: ID is stable when version changes', () => {
+    expect(computeManifestId(APP)).toBe(computeManifestId({ ...APP, version: '2.0.0' }));
+  });
+
+  it('AppManifest: ID changes when authorAddress changes', () => {
+    expect(computeManifestId(APP)).not.toBe(computeManifestId({ ...APP, authorAddress: 'MxOTHER' }));
+  });
+
+  it('AppManifest: ID changes when pearTopicKey changes', () => {
+    expect(computeManifestId(APP)).not.toBe(computeManifestId({ ...APP, pearTopicKey: 'bbbb' }));
+  });
+
+  it('returns the same ID for identical CapabilityManifest inputs', () => {
+    expect(computeManifestId(CAP)).toBe(computeManifestId({ ...CAP }));
+  });
+
+  it('CapabilityManifest: ID is stable when expiresAt changes', () => {
+    expect(computeManifestId(CAP)).toBe(computeManifestId({ ...CAP, expiresAt: 0 }));
+  });
+
+  it('CapabilityManifest: ID changes when agentAddress changes', () => {
+    expect(computeManifestId(CAP)).not.toBe(computeManifestId({ ...CAP, agentAddress: 'MxOTHER' }));
+  });
+
+  it('CapabilityManifest: ID changes when capabilityName changes', () => {
+    expect(computeManifestId(CAP)).not.toBe(computeManifestId({ ...CAP, capabilityName: 'other-capability' }));
+  });
+
+  it('returns the same ID for identical DAppManifest inputs', () => {
+    expect(computeManifestId(DAPP)).toBe(computeManifestId({ ...DAPP }));
+  });
+
+  it('DAppManifest: ID is stable when version changes', () => {
+    expect(computeManifestId(DAPP)).toBe(computeManifestId({ ...DAPP, version: '9.9.9' }));
+  });
+
+  it('DAppManifest: ID changes when contractHash changes', () => {
+    expect(computeManifestId(DAPP)).not.toBe(computeManifestId({ ...DAPP, contractHash: 'dddd' }));
+  });
+
+  it('returns the same ID for identical EdgeServiceManifest inputs', () => {
+    expect(computeManifestId(EDGE)).toBe(computeManifestId({ ...EDGE }));
+  });
+
+  it('EdgeServiceManifest: ID is stable when version changes', () => {
+    expect(computeManifestId(EDGE)).toBe(computeManifestId({ ...EDGE, version: '9.0.0' }));
+  });
+
+  it('EdgeServiceManifest: ID changes when serviceType changes', () => {
+    expect(computeManifestId(EDGE)).not.toBe(computeManifestId({ ...EDGE, serviceType: 'robot' }));
+  });
+
+  it('EdgeServiceManifest: ID changes when name changes', () => {
+    expect(computeManifestId(EDGE)).not.toBe(computeManifestId({ ...EDGE, name: 'Other Sensor' }));
+  });
+
+  it('IDs are 64-character hex strings (SHA3-256)', () => {
+    const id = computeManifestId(APP);
+    expect(id).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('IDs differ across manifest types', () => {
+    const ids = [
+      computeManifestId(APP),
+      computeManifestId(CAP),
+      computeManifestId(DAPP),
+      computeManifestId(EDGE),
+    ];
+    const unique = new Set(ids);
+    expect(unique.size).toBe(4);
+  });
+});