@totemsdk/manifest 0.1.0

package/src/__tests__/sign-verify.test.ts

@@ -0,0 +1,157 @@
+/**
+ * sign-verify.test.ts
+ * Round-trip sign → verify for all four manifest types.
+ * Also tests tamper detection.
+ */
+
+import { signManifest } from '../sign.js';
+import { verifyManifest } from '../verify.js';
+import type {
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+} from '../types.js';
+import { computeManifestId } from '../id.js';
+
+jest.setTimeout(60_000);
+
+const TEST_SEED = new Uint8Array(32).fill(0x42);
+const KEY_INDEX = 0;
+
+const APP: AppManifest = {
+  type: 'app',
+  appId: '',
+  name: 'Test App',
+  version: '1.0.0',
+  authorAddress: 'MxAUTHOR0000000000000000000000000000000000000000',
+  pearTopicKey: 'a'.repeat(64),
+  price: '0',
+  category: ['finance'],
+  permissions: ['wallet:read-balance'],
+  description: 'A test app',
+  minTotemVersion: '0.1.0',
+};
+
+const CAPABILITY: CapabilityManifest = {
+  type: 'capability',
+  capabilityId: '',
+  capabilityName: 'invoice-translate',
+  agentAddress: 'MxAGENT0000000000000000000000000000000000000000',
+  agentIdentityKey: 'b'.repeat(64),
+  description: 'Translates invoices',
+  inputSchema: { type: 'object' },
+  outputSchema: { type: 'object' },
+  pricePerCall: '1',
+  expiresAt: Date.now() + 86_400_000,
+  tags: ['finance'],
+};
+
+const DAPP: DAppManifest = {
+  type: 'dapp',
+  dappId: '',
+  name: 'Test dApp',
+  version: '1.0.0',
+  authorAddress: 'MxAUTHOR0000000000000000000000000000000000000000',
+  contractHash: 'c'.repeat(64),
+  abi: [{ name: 'transfer', description: 'Transfer tokens', params: [{ name: 'amount', type: 'string' }] }],
+  price: '0',
+  category: ['defi'],
+  description: 'A test dApp',
+};
+
+const EDGE: EdgeServiceManifest = {
+  type: 'edge-service',
+  serviceId: '',
+  name: 'Test Sensor',
+  version: '1.0.0',
+  operatorAddress: 'MxOPERATOR000000000000000000000000000000000000',
+  serviceType: 'sensor',
+  description: 'A test sensor node',
+  capabilities: ['temperature'],
+  tags: ['iot'],
+};
+
+function withId<T extends { type: string }>(m: T): T {
+  return m;
+}
+
+describe('signManifest + verifyManifest round-trips', () => {
+  let signedAddress: string;
+
+  beforeAll(async () => {
+    const tmp = await signManifest(APP, TEST_SEED, KEY_INDEX);
+    signedAddress = tmp.authorAddress;
+  });
+
+  it('signs and verifies AppManifest', async () => {
+    const app = { ...APP, authorAddress: signedAddress };
+    const signed = await signManifest(app, TEST_SEED, KEY_INDEX);
+    expect(signed.manifest.type).toBe('app');
+    expect(signed.authorAddress).toBe(signedAddress);
+    expect(signed.signature).toBeTruthy();
+    expect(signed.signerPublicKey).toBeTruthy();
+
+    const result = verifyManifest(signed);
+    expect(result.valid).toBe(true);
+    expect(result.signerAddress).toBe(signedAddress);
+  });
+
+  it('signs and verifies CapabilityManifest', async () => {
+    const cap = { ...CAPABILITY, agentAddress: signedAddress };
+    const signed = await signManifest(cap, TEST_SEED, KEY_INDEX);
+    expect(signed.manifest.type).toBe('capability');
+
+    const result = verifyManifest(signed);
+    expect(result.valid).toBe(true);
+  });
+
+  it('signs and verifies DAppManifest', async () => {
+    const dapp = { ...DAPP, authorAddress: signedAddress };
+    const signed = await signManifest(dapp, TEST_SEED, KEY_INDEX);
+    expect(signed.manifest.type).toBe('dapp');
+
+    const result = verifyManifest(signed);
+    expect(result.valid).toBe(true);
+  });
+
+  it('signs and verifies EdgeServiceManifest', async () => {
+    const edge = { ...EDGE, operatorAddress: signedAddress };
+    const signed = await signManifest(edge, TEST_SEED, KEY_INDEX);
+    expect(signed.manifest.type).toBe('edge-service');
+
+    const result = verifyManifest(signed);
+    expect(result.valid).toBe(true);
+  });
+
+  it('detects manifest tampering — changed name field', async () => {
+    const app = { ...APP, authorAddress: signedAddress };
+    const signed = await signManifest(app, TEST_SEED, KEY_INDEX);
+
+    const tampered = {
+      ...signed,
+      manifest: { ...signed.manifest, name: 'EVIL APP' } as AppManifest,
+    };
+
+    const result = verifyManifest(tampered);
+    expect(result.valid).toBe(false);
+  });
+
+  it('detects tampered authorAddress in SignedManifest wrapper', async () => {
+    const app = { ...APP, authorAddress: signedAddress };
+    const signed = await signManifest(app, TEST_SEED, KEY_INDEX);
+
+    const tampered = { ...signed, authorAddress: 'Mx999999999999999999' };
+    const result = verifyManifest(tampered);
+    expect(result.valid).toBe(false);
+  });
+
+  it('detects corrupted signature bytes', async () => {
+    const app = { ...APP, authorAddress: signedAddress };
+    const signed = await signManifest(app, TEST_SEED, KEY_INDEX);
+
+    const corrupted = { ...signed, signature: 'ff' + signed.signature.slice(2) };
+    const result = verifyManifest(corrupted);
+    expect(result.valid).toBe(false);
+  });
+});

package/src/constants.ts

@@ -0,0 +1,15 @@
+export const MANIFEST_VERSION = 1 as const;
+
+export const MANIFEST_TYPE_BYTE = {
+  app: 0x01,
+  capability: 0x02,
+  dapp: 0x03,
+  'edge-service': 0x04,
+} as const satisfies Record<string, number>;
+
+export const MANIFEST_BYTE_TO_TYPE: Record<number, string> = {
+  0x01: 'app',
+  0x02: 'capability',
+  0x03: 'dapp',
+  0x04: 'edge-service',
+};

package/src/encoding.ts

@@ -0,0 +1,100 @@
+/**
+ * Wire encoding/decoding for SignedManifest.
+ *
+ * Format:
+ *   [1 byte  MANIFEST_VERSION ]
+ *   [1 byte  type discriminant]  0x01=app 0x02=capability 0x03=dapp 0x04=edge-service
+ *   [4 bytes big-endian JSON length]
+ *   [N bytes canonical JSON (UTF-8)]
+ *   [remaining bytes = WOTS signature]
+ *
+ * The JSON payload is the full SignedManifest object (manifest + metadata + signature).
+ * The trailing WOTS signature bytes are stored separately for easy extraction by
+ * the DHT / lookup-protocol layer without needing to parse the JSON.
+ */
+
+import { MANIFEST_VERSION, MANIFEST_TYPE_BYTE, MANIFEST_BYTE_TO_TYPE } from './constants.js';
+import type { SignedManifest, Manifest } from './types.js';
+
+function manifestTypeByte(type: Manifest['type']): number {
+  const byte = MANIFEST_TYPE_BYTE[type];
+  if (byte === undefined) {
+    throw new Error(`encodeManifest: unknown manifest type: ${type}`);
+  }
+  return byte;
+}
+
+export function encodeManifest(signed: SignedManifest): Uint8Array {
+  const enc = new TextEncoder();
+  const json = JSON.stringify(signed);
+  const jsonBytes = enc.encode(json);
+  const sigBytes = hexToBytes(signed.signature);
+
+  const len = jsonBytes.length;
+  const out = new Uint8Array(1 + 1 + 4 + len + sigBytes.length);
+  let offset = 0;
+
+  out[offset++] = MANIFEST_VERSION;
+  out[offset++] = manifestTypeByte(signed.manifest.type);
+  out[offset++] = (len >>> 24) & 0xff;
+  out[offset++] = (len >>> 16) & 0xff;
+  out[offset++] = (len >>> 8) & 0xff;
+  out[offset++] = len & 0xff;
+  out.set(jsonBytes, offset);
+  offset += len;
+  out.set(sigBytes, offset);
+
+  return out;
+}
+
+export function decodeManifest(bytes: Uint8Array): SignedManifest {
+  if (bytes.length < 6) {
+    throw new Error('decodeManifest: buffer too short (< 6 bytes)');
+  }
+
+  const version = bytes[0];
+  if (version !== MANIFEST_VERSION) {
+    throw new Error(`decodeManifest: unsupported MANIFEST_VERSION ${version}`);
+  }
+
+  const typeByte = bytes[1];
+  const expectedType = MANIFEST_BYTE_TO_TYPE[typeByte];
+  if (!expectedType) {
+    throw new Error(`decodeManifest: unknown type discriminant 0x${typeByte.toString(16).padStart(2, '0')}`);
+  }
+
+  const jsonLen =
+    (bytes[2] << 24) | (bytes[3] << 16) | (bytes[4] << 8) | bytes[5];
+
+  if (bytes.length < 6 + jsonLen) {
+    throw new Error(`decodeManifest: buffer too short for declared JSON length ${jsonLen}`);
+  }
+
+  const jsonBytes = bytes.slice(6, 6 + jsonLen);
+  const json = new TextDecoder().decode(jsonBytes);
+
+  let signed: SignedManifest;
+  try {
+    signed = JSON.parse(json) as SignedManifest;
+  } catch (e) {
+    throw new Error(`decodeManifest: invalid JSON payload: ${String(e)}`);
+  }
+
+  if (signed.manifest?.type !== expectedType) {
+    throw new Error(
+      `decodeManifest: type discriminant mismatch — wire says '${expectedType}' but JSON manifest.type is '${signed.manifest?.type}'`,
+    );
+  }
+
+  return signed;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.startsWith('0x')) hex = hex.slice(2);
+  if (hex.length % 2 !== 0) throw new Error('hexToBytes: odd-length hex string');
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}

package/src/guards.ts

@@ -0,0 +1,48 @@
+/**
+ * Type guards for manifest kinds.
+ * Each guard accepts a raw Manifest or a SignedManifest.
+ */
+
+import type {
+  Manifest,
+  SignedManifest,
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+} from './types.js';
+
+type MaybeSignedOrRaw = Manifest | SignedManifest | null | undefined;
+
+function getRawManifest(input: MaybeSignedOrRaw): Manifest | null {
+  if (!input || typeof input !== 'object') return null;
+  if ('manifest' in input && input.manifest && typeof input.manifest === 'object') {
+    return (input as SignedManifest).manifest;
+  }
+  if ('type' in input) return input as Manifest;
+  return null;
+}
+
+export function isAppManifest(
+  input: MaybeSignedOrRaw,
+): input is AppManifest | SignedManifest<AppManifest> {
+  return getRawManifest(input)?.type === 'app';
+}
+
+export function isCapabilityManifest(
+  input: MaybeSignedOrRaw,
+): input is CapabilityManifest | SignedManifest<CapabilityManifest> {
+  return getRawManifest(input)?.type === 'capability';
+}
+
+export function isDAppManifest(
+  input: MaybeSignedOrRaw,
+): input is DAppManifest | SignedManifest<DAppManifest> {
+  return getRawManifest(input)?.type === 'dapp';
+}
+
+export function isEdgeServiceManifest(
+  input: MaybeSignedOrRaw,
+): input is EdgeServiceManifest | SignedManifest<EdgeServiceManifest> {
+  return getRawManifest(input)?.type === 'edge-service';
+}

package/src/id.ts

@@ -0,0 +1,46 @@
+/**
+ * computeManifestId — deterministic stable ID for any manifest.
+ *
+ * The ID is SHA3-256 over a type-specific stable key string.
+ * It must be stable across version bumps (version is NOT part of the input).
+ *
+ * Stable key rules:
+ *   AppManifest        → "app"        + authorAddress + pearTopicKey
+ *   CapabilityManifest → "capability" + agentAddress  + capabilityName
+ *   DAppManifest       → "dapp"       + authorAddress + contractHash
+ *   EdgeServiceManifest → "edge-service" + operatorAddress + serviceType + name
+ */
+
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import type { Manifest } from './types.js';
+
+function bytesToHex(b: Uint8Array): string {
+  return Array.from(b)
+    .map((x) => x.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export function computeManifestId(manifest: Manifest): string {
+  let stableKey: string;
+
+  switch (manifest.type) {
+    case 'app':
+      stableKey = `app\0${manifest.authorAddress}\0${manifest.pearTopicKey}`;
+      break;
+    case 'capability':
+      stableKey = `capability\0${manifest.agentAddress}\0${manifest.capabilityName}`;
+      break;
+    case 'dapp':
+      stableKey = `dapp\0${manifest.authorAddress}\0${manifest.contractHash}`;
+      break;
+    case 'edge-service':
+      stableKey = `edge-service\0${manifest.operatorAddress}\0${manifest.serviceType}\0${manifest.name}`;
+      break;
+    default: {
+      const _exhaustive: never = manifest;
+      throw new Error(`computeManifestId: unknown manifest type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+
+  return bytesToHex(sha3_256(new TextEncoder().encode(stableKey)));
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export type {
+  AppManifest,
+  CapabilityManifest,
+  DAppManifest,
+  EdgeServiceManifest,
+  EdgeServiceType,
+  Manifest,
+  SignedManifest,
+  AppPermission,
+  DAppAbiEntry,
+  VerifyResult,
+} from './types.js';
+
+export { MANIFEST_VERSION } from './constants.js';
+
+export { computeManifestId } from './id.js';
+export { signManifest } from './sign.js';
+export { verifyManifest } from './verify.js';
+export { encodeManifest, decodeManifest } from './encoding.js';
+
+export {
+  isAppManifest,
+  isCapabilityManifest,
+  isDAppManifest,
+  isEdgeServiceManifest,
+} from './guards.js';

package/src/sign.ts

@@ -0,0 +1,63 @@
+/**
+ * signManifest — signs a manifest with a WOTS key.
+ *
+ * Steps:
+ *   1. Canonicalise the manifest as deterministic JSON (sorted keys).
+ *   2. SHA3-256 the UTF-8 bytes → 32-byte digest.
+ *   3. Sign with wotsSign(seed, keyIndex, digest).
+ *   4. Derive address + PKdigest via wotsKeypairFromSeed + wotsAddressFromKeypair.
+ *   5. Return SignedManifest<T>.
+ *
+ * signerPublicKey in SignedManifest is the 32-byte WOTS PKdigest (hex, 64 chars).
+ * This is the exact value expected by verifyManifest (via wotsVerifyDigest).
+ *
+ * The caller is responsible for reserving the WOTS key index before calling
+ * this function. This package does NOT depend on @totemsdk/wots-lease.
+ */
+
+import { sha3_256 } from '@noble/hashes/sha3.js';
+import {
+  wotsSign,
+  wotsKeypairFromSeed,
+  wotsAddressFromKeypair,
+  bytesToHex,
+} from '@totemsdk/core';
+import type { Manifest, SignedManifest } from './types.js';
+
+/** Produce a deterministic canonical JSON string with sorted keys (recursive). */
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalJson).join(',') + ']';
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  const pairs = keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+  return '{' + pairs.join(',') + '}';
+}
+
+export function manifestDigest(manifest: Manifest): Uint8Array {
+  const canonical = canonicalJson(manifest);
+  return sha3_256(new TextEncoder().encode(canonical));
+}
+
+export async function signManifest<T extends Manifest>(
+  manifest: T,
+  seed: Uint8Array,
+  keyIndex: number,
+): Promise<SignedManifest<T>> {
+  const digest = manifestDigest(manifest);
+  const sigBytes = wotsSign(seed, keyIndex, digest);
+  const kp = wotsKeypairFromSeed(seed, keyIndex);
+  const address = wotsAddressFromKeypair(kp);
+
+  return {
+    manifest,
+    authorAddress: address,
+    signerPublicKey: bytesToHex(kp.pk),
+    signedAt: Date.now(),
+    signature: bytesToHex(sigBytes),
+  };
+}

package/src/types.ts

@@ -0,0 +1,140 @@
+/**
+ * @totemsdk/manifest — Manifest type definitions
+ *
+ * Four manifest categories for the MVP:
+ *   AppManifest        — human-facing Pear app
+ *   CapabilityManifest — ephemeral AI/agent service
+ *   DAppManifest       — KISSVM contract / covenant
+ *   EdgeServiceManifest — any persistent Totem Edge service
+ *
+ * No network, no blockchain, no Hyperswarm — pure schema.
+ */
+
+export type AppPermission =
+  | 'wallet:read-balance'
+  | 'wallet:request-payment'
+  | 'omnia:open-channel'
+  | 'omnia:update-channel'
+  | 'lookup:watch-address'
+  | 'kissvm:evaluate'
+  | 'qvac:call-agent';
+
+export interface AppManifest {
+  type: 'app';
+  appId: string;
+  name: string;
+  version: string;
+  authorAddress: string;
+  pearTopicKey: string;
+  price: string;
+  priceToken?: string;
+  subscriptionInterval?: number;
+  category: string[];
+  permissions: AppPermission[];
+  iconCid?: string;
+  description: string;
+  repoUrl?: string;
+  minTotemVersion: string;
+}
+
+export interface CapabilityManifest {
+  type: 'capability';
+  capabilityId: string;
+  capabilityName: string;
+  agentAddress: string;
+  agentIdentityKey: string;
+  description: string;
+  inputSchema: object;
+  outputSchema: object;
+  pricePerCall: string;
+  priceToken?: string;
+  paymentChannel?: 'omnia' | 'onchain';
+  maxLatencyMs?: number;
+  maxCallsPerMinute?: number;
+  expiresAt: number;
+  tags: string[];
+}
+
+export interface DAppAbiEntry {
+  name: string;
+  description: string;
+  params: { name: string; type: string; description?: string }[];
+}
+
+export interface DAppManifest {
+  type: 'dapp';
+  dappId: string;
+  name: string;
+  version: string;
+  authorAddress: string;
+  contractHash: string;
+  contractSource?: string;
+  abi: DAppAbiEntry[];
+  price: string;
+  priceToken?: string;
+  category: string[];
+  description: string;
+  auditReport?: string;
+}
+
+export type EdgeServiceType =
+  | 'sensor'
+  | 'robot'
+  | 'mqtt-feed'
+  | 'proof-index'
+  | 'lookup-provider'
+  | 'omnia-router'
+  | 'calibration-authority'
+  | 'verifier'
+  | 'machine-service'
+  | 'other';
+
+export interface EdgeServiceManifest {
+  type: 'edge-service';
+  serviceId: string;
+  name: string;
+  version: string;
+  operatorAddress: string;
+  serviceType: EdgeServiceType;
+  description: string;
+  endpoints?: Array<{
+    type: 'https' | 'mqtt' | 'hyperswarm' | 'websocket' | 'other';
+    uri: string;
+  }>;
+  capabilities: string[];
+  price?: string;
+  priceToken?: string;
+  paymentMethods?: Array<'omnia' | 'onchain' | 'invoice' | 'free'>;
+  tags: string[];
+  expiresAt?: number;
+  minTotemVersion?: string;
+}
+
+export type Manifest =
+  | AppManifest
+  | CapabilityManifest
+  | DAppManifest
+  | EdgeServiceManifest;
+
+/**
+ * Wraps any manifest with a WOTS signature.
+ *
+ * `signerPublicKey` — hex of the full WOTS public key (required for
+ * self-contained verification via verifyManifest).
+ * `authorAddress`  — the Minima address of the signer, derived at sign time
+ *   and stored for quick policy checks without re-deriving from the public key.
+ */
+export interface SignedManifest<T extends Manifest = Manifest> {
+  manifest: T;
+  authorAddress: string;
+  signerPublicKey: string;
+  signedAt: number;
+  signature: string;
+  rootIdentityProof?: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  reason?: string;
+  signerAddress: string;
+}

package/src/verify.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { SignedManifest, VerifyResult } from './types.js';
+import { manifestDigest } from './sign.js';
+
+function manifestAddressField(manifest: SignedManifest['manifest']): string {
+  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: never = manifest;
+      throw new Error(`verifyManifest: unknown manifest type: ${JSON.stringify(_exhaustive)}`);
+    }
+  }
+}
+
+export function verifyManifest(signed: SignedManifest): VerifyResult {
+  const { manifest, signature, signerPublicKey, authorAddress } = signed;
+
+  let sigBytes: Uint8Array;
+  let pkDigest: Uint8Array;
+  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: boolean;
+  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 };
+}