zpk1-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 o0CroMag0o
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# zpk1
+
+Strict parser / validator / packer for the **ZPK1** packed payload protocol.
+
+ZPK1 is a deterministic, pipe-delimited, human-readable format for pre-hashed payloads intended for timestamping or attestation without transmitting raw data.
+
+This package enforces the ZPK1 specification only. It does not perform hashing or timestamping. To obtain verifiable time receipts, submit a valid ZPK1 string to a timestamping authority (e.g., ZEUS Verify).
+
+Design goals:
+
+- minimal surface area
+- strict structural enforcement
+- zero dependencies
+- no silent normalization
+- deterministic behavior across environments
+
+## Install
+
+```bash
+npm i zpk1

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+export type ZPK1Canon = "utf8_exact" | "json_sorted_compact" | "bytes_b64";
+export type ZPK1Algo = "blake3" | "sha256";
+export type ZPK1Parsed = {
+    version: "ZPK1";
+    canon: ZPK1Canon;
+    algo: ZPK1Algo;
+    digest: string;
+    tag?: string;
+};
+export type ZPK1ErrorCode = "ZPK1_BAD_PREFIX" | "ZPK1_WHITESPACE" | "ZPK1_BAD_ORDER" | "ZPK1_MISSING_FIELD" | "ZPK1_EXTRA_FIELD" | "ZPK1_BAD_KV" | "ZPK1_BAD_CANON" | "ZPK1_BAD_ALGO" | "ZPK1_BAD_DIGEST" | "ZPK1_BAD_TAG";
+export declare class ZPK1Error extends Error {
+    code: ZPK1ErrorCode;
+    details?: Record<string, unknown>;
+    constructor(code: ZPK1ErrorCode, message: string, details?: Record<string, unknown>);
+}
+export declare function parse(zpk: string): ZPK1Parsed;
+export declare function isZPK1(zpk: string): boolean;
+export declare function assert(zpk: string): ZPK1Parsed;
+export declare function validate(zpk: string): {
+    ok: true;
+    value: ZPK1Parsed;
+} | {
+    ok: false;
+    error: ZPK1Error;
+};
+export declare function pack(input: {
+    canon: ZPK1Canon;
+    algo: ZPK1Algo;
+    digest: string;
+    tag?: string;
+}): string;

package/dist/src/index.js

@@ -0,0 +1,122 @@
+export class ZPK1Error extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "ZPK1Error";
+        this.code = code;
+        this.details = details;
+    }
+}
+const ALLOWED_CANON = new Set(["utf8_exact", "json_sorted_compact", "bytes_b64"]);
+const ALLOWED_ALGO = new Set(["blake3", "sha256"]);
+const HEX64 = /^[0-9a-f]{64}$/;
+function hasWhitespace(s) {
+    // Disallow any whitespace anywhere
+    return /\s/.test(s);
+}
+function parseKV(part) {
+    const idx = part.indexOf("=");
+    if (idx <= 0 || idx === part.length - 1) {
+        throw new ZPK1Error("ZPK1_BAD_KV", "Malformed key/value field (expected key=value).", { part });
+    }
+    const key = part.slice(0, idx);
+    const value = part.slice(idx + 1);
+    return { key, value };
+}
+export function parse(zpk) {
+    if (typeof zpk !== "string") {
+        throw new ZPK1Error("ZPK1_BAD_PREFIX", "Input must be a string.");
+    }
+    if (hasWhitespace(zpk)) {
+        throw new ZPK1Error("ZPK1_WHITESPACE", "Whitespace is not permitted in ZPK1.");
+    }
+    const parts = zpk.split("|");
+    if (parts.length < 4) {
+        throw new ZPK1Error("ZPK1_MISSING_FIELD", "ZPK1 requires at least 4 pipe-delimited parts.");
+    }
+    const prefix = parts[0];
+    if (prefix !== "ZPK1") {
+        throw new ZPK1Error("ZPK1_BAD_PREFIX", "ZPK1 must begin with literal prefix 'ZPK1'.", { prefix });
+    }
+    // Allowed field sequences:
+    // ZPK1|canon=...|algo=...|digest=...
+    // ZPK1|canon=...|algo=...|tag=...|digest=...
+    const kvs = parts.slice(1).map(parseKV);
+    // Enforce exact keys and order
+    const keys = kvs.map(k => k.key);
+    const hasTag = keys.includes("tag");
+    const expected = hasTag
+        ? ["canon", "algo", "tag", "digest"]
+        : ["canon", "algo", "digest"];
+    // No extra fields allowed
+    if (keys.length !== expected.length) {
+        throw new ZPK1Error("ZPK1_EXTRA_FIELD", "Unexpected number of fields.", { keys, expected });
+    }
+    for (let i = 0; i < expected.length; i++) {
+        if (keys[i] !== expected[i]) {
+            throw new ZPK1Error("ZPK1_BAD_ORDER", "Fields must appear in strict order.", { keys, expected });
+        }
+    }
+    const canon = kvs[0].value;
+    const algo = kvs[1].value;
+    if (!ALLOWED_CANON.has(canon)) {
+        throw new ZPK1Error("ZPK1_BAD_CANON", "Unsupported canon value.", { canon });
+    }
+    if (!ALLOWED_ALGO.has(algo)) {
+        throw new ZPK1Error("ZPK1_BAD_ALGO", "Unsupported algo value.", { algo });
+    }
+    let tag;
+    let digest;
+    if (hasTag) {
+        tag = kvs[2].value;
+        digest = kvs[3].value;
+        if (!tag || tag.length === 0) {
+            throw new ZPK1Error("ZPK1_BAD_TAG", "Tag must not be empty.");
+        }
+        if (tag.includes("|") || tag.includes("=")) {
+            throw new ZPK1Error("ZPK1_BAD_TAG", "Tag must not contain '|' or '='.", { tag });
+        }
+    }
+    else {
+        digest = kvs[2].value;
+    }
+    if (!HEX64.test(digest)) {
+        throw new ZPK1Error("ZPK1_BAD_DIGEST", "Digest must be 64 lowercase hex characters.", { digest });
+    }
+    return {
+        version: "ZPK1",
+        canon: canon,
+        algo: algo,
+        digest,
+        ...(tag ? { tag } : {}),
+    };
+}
+export function isZPK1(zpk) {
+    try {
+        parse(zpk);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function assert(zpk) {
+    return parse(zpk);
+}
+export function validate(zpk) {
+    try {
+        return { ok: true, value: parse(zpk) };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof ZPK1Error ? e : new ZPK1Error("ZPK1_BAD_KV", "Unknown ZPK1 error.") };
+    }
+}
+export function pack(input) {
+    // Validate using same rules (don’t allow pack to create invalid strings)
+    const base = `ZPK1|canon=${input.canon}|algo=${input.algo}`;
+    const mid = input.tag !== undefined ? `${base}|tag=${input.tag}|digest=${input.digest}` : `${base}|digest=${input.digest}`;
+    // Re-parse to enforce strictness
+    parse(mid);
+    return mid;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "zpk1-protocol",
+  "version": "0.1.0",
+  "description": "Strict parser, validator, and packer for the ZPK1 packed payload protocol.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "keywords": [
+    "zpk1",
+    "protocol",
+    "validator",
+    "attestation",
+    "timestamp",
+    "zeus",
+    "hash"
+  ],
+  "author": "Drew",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}