@provex/manifest 1.9.2-rc.20260719220119.92e7405

package/README.md

@@ -0,0 +1,15 @@
+# @provex/manifest
+
+Pure helpers for Provex release manifests — the standardized `version.json`
+a decentralized application serves to declare a release.
+
+- `parseManifest` — validate an unknown value into a `ReleaseManifest`.
+- `canonicalize` — deterministic canonical-JSON bytes (sorted keys, no
+  insignificant whitespace) so reformatting never changes the hash.
+- `manifestHash` — the keccak256 of the canonical bytes; the unit a release
+  is proven and endorsed against.
+- `dappKey` — keccak256 of the lowercased domain; the per-application key.
+- `fetchManifest` — retrieve and validate a live manifest from a domain,
+  trying `/version.json` then `/.well-known/version.json`.
+
+Browser-safe and dependency-light (Zod plus viem as a peer).

package/dist/canonicalize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Constrained canonical-JSON for release manifests.
+ *
+ * Equivalent to RFC 8785 (JSON Canonicalization Scheme) over the manifest's
+ * restricted value space: the schema forbids floats and non-finite numbers,
+ * so recursive key sorting plus `JSON.stringify` of each primitive yields a
+ * single, stable byte sequence for a given manifest. If a future schema
+ * version admits arbitrary values, replace `canonicalizeValue` with a full
+ * RFC 8785 implementation behind this same signature.
+ */
+import type { ReleaseManifest } from './schema.js';
+/**
+ * Deterministic canonical-JSON bytes for a manifest. Key order and whitespace
+ * in the source do not affect the output.
+ */
+export declare const canonicalize: (manifest: ReleaseManifest) => Uint8Array;

package/dist/canonicalize.js

@@ -0,0 +1,32 @@
+/**
+ * Constrained canonical-JSON for release manifests.
+ *
+ * Equivalent to RFC 8785 (JSON Canonicalization Scheme) over the manifest's
+ * restricted value space: the schema forbids floats and non-finite numbers,
+ * so recursive key sorting plus `JSON.stringify` of each primitive yields a
+ * single, stable byte sequence for a given manifest. If a future schema
+ * version admits arbitrary values, replace `canonicalizeValue` with a full
+ * RFC 8785 implementation behind this same signature.
+ */
+const canonicalizeValue = (value) => {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalizeValue).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        const members = Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalizeValue(record[key])}`);
+        return `{${members.join(',')}}`;
+    }
+    // string | number (integer) | boolean — JSON.stringify is canonical here.
+    return JSON.stringify(value);
+};
+/**
+ * Deterministic canonical-JSON bytes for a manifest. Key order and whitespace
+ * in the source do not affect the output.
+ */
+export const canonicalize = (manifest) => new TextEncoder().encode(canonicalizeValue(manifest));

package/dist/fetch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Retrieve and validate a live release manifest from a domain.
+ *
+ * Tries the root `/version.json` first, then the `/.well-known/version.json`
+ * fallback. The returned `dappKey` derives from the manifest's self-declared
+ * `domain` (the same value the gate will bind a proof to), not from the
+ * request origin, so a client preview matches what the gate signs.
+ */
+import type { Hex } from 'viem';
+import { type ReleaseManifest } from './schema.js';
+export interface FetchedManifest {
+    manifest: ReleaseManifest;
+    manifestHash: Hex;
+    dappKey: Hex;
+    origin: string;
+}
+export declare const fetchManifest: (origin: string) => Promise<FetchedManifest>;

package/dist/fetch.js

@@ -0,0 +1,31 @@
+/**
+ * Retrieve and validate a live release manifest from a domain.
+ *
+ * Tries the root `/version.json` first, then the `/.well-known/version.json`
+ * fallback. The returned `dappKey` derives from the manifest's self-declared
+ * `domain` (the same value the gate will bind a proof to), not from the
+ * request origin, so a client preview matches what the gate signs.
+ */
+import { parseManifest } from './schema.js';
+import { manifestHash, dappKey } from './hash.js';
+const MANIFEST_PATHS = ['/version.json', '/.well-known/version.json'];
+const normalizeOrigin = (origin) => {
+    const withScheme = /^https?:\/\//i.test(origin) ? origin : `https://${origin}`;
+    return withScheme.replace(/\/+$/, '');
+};
+export const fetchManifest = async (origin) => {
+    const base = normalizeOrigin(origin);
+    for (const path of MANIFEST_PATHS) {
+        const response = await fetch(`${base}${path}`);
+        if (!response.ok)
+            continue;
+        const manifest = parseManifest(await response.json());
+        return {
+            manifest,
+            manifestHash: manifestHash(manifest),
+            dappKey: dappKey(manifest.domain),
+            origin: base,
+        };
+    }
+    throw new Error(`No valid release manifest found at ${base}`);
+};

package/dist/hash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hash helpers binding a release to a deterministic identifier.
+ *
+ * - `manifestHash` is the unit a release is proven and endorsed against.
+ * - `dappKey` is the stable per-application key (the timeline subject),
+ *   derived from the domain. When an on-chain registry later owns dapp
+ *   identity, `dappKey` switches to the registry identifier; consumers treat
+ *   it as an opaque 32-byte value, so the signature does not change.
+ */
+import { type Hex } from 'viem';
+import type { ReleaseManifest } from './schema.js';
+/** keccak256 of the canonical-JSON bytes of the manifest. */
+export declare const manifestHash: (manifest: ReleaseManifest) => Hex;
+/** keccak256 of the lowercased domain, encoded as hex. */
+export declare const dappKey: (domain: string) => Hex;

package/dist/hash.js

@@ -0,0 +1,15 @@
+/**
+ * Hash helpers binding a release to a deterministic identifier.
+ *
+ * - `manifestHash` is the unit a release is proven and endorsed against.
+ * - `dappKey` is the stable per-application key (the timeline subject),
+ *   derived from the domain. When an on-chain registry later owns dapp
+ *   identity, `dappKey` switches to the registry identifier; consumers treat
+ *   it as an opaque 32-byte value, so the signature does not change.
+ */
+import { keccak256, stringToHex } from 'viem';
+import { canonicalize } from './canonicalize.js';
+/** keccak256 of the canonical-JSON bytes of the manifest. */
+export const manifestHash = (manifest) => keccak256(canonicalize(manifest));
+/** keccak256 of the lowercased domain, encoded as hex. */
+export const dappKey = (domain) => keccak256(stringToHex(domain.toLowerCase()));

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @provex/manifest — release-manifest standard helpers.
+ * The shared contract guaranteeing the browser, gate, indexer, and UI derive
+ * identical hashes for the same release.
+ */
+export { parseManifest, ReleaseManifestSchema, type ReleaseManifest } from './schema.js';
+export { canonicalize } from './canonicalize.js';
+export { manifestHash, dappKey } from './hash.js';
+export { fetchManifest, type FetchedManifest } from './fetch.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @provex/manifest — release-manifest standard helpers.
+ * The shared contract guaranteeing the browser, gate, indexer, and UI derive
+ * identical hashes for the same release.
+ */
+export { parseManifest, ReleaseManifestSchema } from './schema.js';
+export { canonicalize } from './canonicalize.js';
+export { manifestHash, dappKey } from './hash.js';
+export { fetchManifest } from './fetch.js';

package/dist/schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Release-manifest schema and parser.
+ *
+ * A release manifest is the standardized `version.json` a decentralized
+ * application serves to declare a release. The schema is strict: unknown
+ * fields are rejected so the hashed value space stays tight and predictable.
+ */
+import { z } from 'zod';
+export declare const ReleaseManifestSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"provex-release/1">;
+    name: z.ZodString;
+    domain: z.ZodString;
+    version: z.ZodString;
+    released: z.ZodString;
+    frontend: z.ZodOptional<z.ZodObject<{
+        cid: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        cid: string;
+    }, {
+        cid: string;
+    }>>;
+    contracts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        chain: z.ZodNumber;
+        address: z.ZodString;
+        codeHash: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        chain: number;
+        address: string;
+        codeHash?: string | undefined;
+    }, {
+        chain: number;
+        address: string;
+        codeHash?: string | undefined;
+    }>, "many">>;
+    links: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    schema: "provex-release/1";
+    name: string;
+    domain: string;
+    version: string;
+    released: string;
+    frontend?: {
+        cid: string;
+    } | undefined;
+    contracts?: {
+        chain: number;
+        address: string;
+        codeHash?: string | undefined;
+    }[] | undefined;
+    links?: Record<string, string> | undefined;
+}, {
+    schema: "provex-release/1";
+    name: string;
+    domain: string;
+    version: string;
+    released: string;
+    frontend?: {
+        cid: string;
+    } | undefined;
+    contracts?: {
+        chain: number;
+        address: string;
+        codeHash?: string | undefined;
+    }[] | undefined;
+    links?: Record<string, string> | undefined;
+}>;
+export type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
+/**
+ * Validate an unknown value into a {@link ReleaseManifest}.
+ * @throws ZodError if the value is not a well-formed manifest.
+ */
+export declare const parseManifest: (input: unknown) => ReleaseManifest;

package/dist/schema.js

@@ -0,0 +1,41 @@
+/**
+ * Release-manifest schema and parser.
+ *
+ * A release manifest is the standardized `version.json` a decentralized
+ * application serves to declare a release. The schema is strict: unknown
+ * fields are rejected so the hashed value space stays tight and predictable.
+ */
+import { z } from 'zod';
+const hostnameSchema = z
+    .string()
+    .regex(/^[a-z0-9.-]+$/i, 'Expected a bare hostname, e.g. "pulsex.com"');
+const addressSchema = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{40}$/, 'Expected a 0x-prefixed 20-byte address');
+const codeHashSchema = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{64}$/, 'Expected a 0x-prefixed 32-byte hash');
+const contractSchema = z
+    .object({
+    chain: z.number().int().positive(),
+    address: addressSchema,
+    codeHash: codeHashSchema.optional(),
+})
+    .strict();
+export const ReleaseManifestSchema = z
+    .object({
+    schema: z.literal('provex-release/1'),
+    name: z.string().min(1),
+    domain: hostnameSchema,
+    version: z.string().min(1),
+    released: z.string().datetime(), // ISO-8601, UTC ("Z"); offsets rejected
+    frontend: z.object({ cid: z.string().min(1) }).strict().optional(),
+    contracts: z.array(contractSchema).optional(),
+    links: z.record(z.string()).optional(),
+})
+    .strict();
+/**
+ * Validate an unknown value into a {@link ReleaseManifest}.
+ * @throws ZodError if the value is not a well-formed manifest.
+ */
+export const parseManifest = (input) => ReleaseManifestSchema.parse(input);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@provex/manifest",
+  "version": "1.9.2-rc.20260719220119.92e7405",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/provex-tech/monorepo.git",
+    "directory": "packages/manifest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "test:watch": "node --import tsx --test --watch 'src/**/*.test.ts'"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "viem": "^2.38.0"
+  }
+}