@zanii/blackbox 0.3.0 → 0.4.0

package/dist/evidence/index.js

@@ -0,0 +1,151 @@
+// The court evidence pack (spec/investigations.md §7): why a court, or an expert it appoints, can
+// rely on a record, and how to check it without trusting the operator. Arabic and English. Pure;
+// mirrors sdks/python/src/zanii_blackbox/evidence.py; pinned by spec/vectors/evidence-pack.json.
+import { hashLine } from "../verify/envelope.js";
+const LEGAL_BASIS = {
+    en: "Under UAE Federal Decree-Law No. 46 of 2021 on Electronic Transactions and Trust Services, an electronic record and an electronic signature have legal effect and may be admitted as evidence. This pack lets a court, or an expert it appoints, check the record's integrity and origin independently, without relying on the operator. It maps the evidence; it is not legal advice.",
+    ar: "بموجب المرسوم بقانون اتحادي رقم 46 لسنة 2021 في شأن المعاملات الإلكترونية وخدمات الثقة، يكون للسجل الإلكتروني والتوقيع الإلكتروني أثر قانوني ويجوز قبولهما دليلًا. تتيح هذه الحزمة للمحكمة، أو لخبير تعيّنه، التحقق المستقل من سلامة السجل ومصدره دون الاعتماد على المشغّل. هي بيان للأدلة، وليست استشارة قانونية.",
+};
+const STEPS = [
+    {
+        en: "The hash chain: each event's hash covers its content and the previous event's hash (SHA-256 over RFC 8785 JSON). Recomputing them gives the last hash shown above.",
+        ar: "سلسلة التجزئة: تجزئة كل حدث تشمل محتواه وتجزئة الحدث السابق (SHA-256 على JSON وفق RFC 8785). إعادة حسابها تعطي آخر تجزئة المذكورة أعلاه.",
+    },
+    {
+        en: "The bodies: each body's SHA-256 matches the hash its event recorded. An erased body is gone, but its hash stays, so the chain still checks.",
+        ar: "المحتوى: تطابق تجزئة SHA-256 لكل محتوى التجزئةَ التي سجّلها حدثه. المحتوى الممحوّ لم يعد موجودًا، لكن تجزئته باقية، فتبقى السلسلة قابلة للتحقق.",
+    },
+    {
+        en: "The anchors: each ledger receipt commits to the session, its number of events and its last hash, and is signed by the gateway's DID under a delegation from its owner.",
+        ar: "التثبيت: كل إيصال في دفتر الأستاذ يلتزم بالجلسة وعدد أحداثها وآخر تجزئة لها، وموقّع بهوية البوابة (DID) بتفويض من مالكها.",
+    },
+    {
+        en: "The ledger: each receipt is in the ledger's Merkle log (an inclusion proof) under a signed tree head, and the log only ever grew.",
+        ar: "دفتر الأستاذ: كل إيصال مُدرَج في سجل ميركل الخاص بدفتر الأستاذ (إثبات إدراج) تحت رأس شجرة موقّع، والسجل لم يزد إلا نموًّا.",
+    },
+    {
+        en: "The gateway's own log, when present: the session's signed statement, its inclusion in the gateway's transparency log, the witnesses' cosignatures and the RFC 3161 time-stamp.",
+        ar: "سجل البوابة نفسها، إن وُجد: البيان الموقّع للجلسة، وإدراجه في سجل الشفافية للبوابة، وتواقيع الشهود المشتركة، والختم الزمني وفق RFC 3161.",
+    },
+];
+const REPRODUCE = [
+    "npx @zanii/blackbox verify bundle.json --proofs",
+    "pip install zanii-blackbox && blackbox verify bundle.json --proofs",
+];
+const parse = (line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return {};
+    }
+};
+/** spec/investigations.md §7. */
+export function evidencePack(bundle, report, opts) {
+    const lines = bundle.lines;
+    const first = lines.length ? parse(lines[0]) : {};
+    const last = lines.length ? parse(lines.at(-1)) : {};
+    const open = first.kind === "session.open" ? first : {};
+    const newest = bundle.anchors.at(-1);
+    const t = bundle.transparency;
+    const proofs = report.proofs === null || opts.proofs === "not_checked"
+        ? "not_checked"
+        : report.proofs.every((p) => p.ok)
+            ? "checked"
+            : "failed";
+    return {
+        v: 1,
+        kind: "blackbox-evidence-pack",
+        session_id: bundle.session.session_id,
+        label: typeof bundle.session.label === "string" ? bundle.session.label : null,
+        agent: open.meta?.agent ?? null,
+        anchored_by: bundle.anchored_by,
+        ledger_url: bundle.ledger_url,
+        record: {
+            events: lines.length,
+            head: lines.length ? hashLine(lines.at(-1)) : null,
+            first_at: typeof first.ts === "string" ? first.ts : null,
+            last_at: typeof last.ts === "string" ? last.ts : null,
+            closed: last.kind === "session.close",
+        },
+        anchors: {
+            count: bundle.anchors.length,
+            last: newest
+                ? {
+                    count: newest.count,
+                    receipt_hash: newest.receipt_hash,
+                    anchored_at: newest.anchored_at,
+                }
+                : null,
+        },
+        transparency: t
+            ? {
+                statement: t.statement !== undefined,
+                receipt: t.receipt !== undefined,
+                checkpoint: t.checkpoint !== undefined,
+                timestamp: t.timestamp !== undefined,
+            }
+            : null,
+        verified: report.ok,
+        verification: {
+            chain: report.chain.ok ? "ok" : report.chain.code,
+            identity: report.identity.ok ? "ok" : "mismatch",
+            proofs,
+        },
+        legal_basis: LEGAL_BASIS,
+        steps: STEPS.map((s, i) => ({ n: i + 1, ...s })),
+        reproduce: REPRODUCE,
+        generated_at: opts.generated_at,
+        bundle_sha256: opts.bundle_sha256,
+    };
+}
+// U+2067 … U+2069 isolate the Arabic paragraphs, so they read right to left in any viewer.
+const rtl = (s) => `⁧${s}⁩`;
+/** The Markdown copy (spec/investigations.md §7): `en`, `ar` or `both`. */
+export function renderEvidencePack(pack, lang = "both") {
+    const show = (b) => lang === "en" ? b.en : lang === "ar" ? rtl(b.ar) : `${b.en}\n\n> ${rtl(b.ar)}`;
+    const label = (en, ar) => lang === "en" ? en : lang === "ar" ? rtl(ar) : `${en} / ${rtl(ar)}`;
+    const r = pack.record;
+    const verdict = pack.verified
+        ? label("VERIFIED", "تم التحقق")
+        : label("FAILED VERIFICATION", "فشل التحقق");
+    const rows = [
+        [label("Session", "الجلسة"), `\`${pack.session_id}\``],
+        [label("Label", "التسمية"), pack.label ? pack.label.replaceAll("|", "\\|") : "—"],
+        [label("Events", "الأحداث"), String(r.events)],
+        [label("Last hash", "آخر تجزئة"), r.head ? `\`${r.head}\`` : "—"],
+        [label("Period", "المدة"), `${r.first_at ?? "—"} → ${r.last_at ?? "—"}`],
+        [label("Closed", "مغلقة"), r.closed ? label("yes", "نعم") : label("no", "لا")],
+        [label("Anchored by", "ثبّتها"), pack.anchored_by ? `\`${pack.anchored_by}\`` : "—"],
+        [label("Anchors", "التثبيتات"), String(pack.anchors.count)],
+        [label("Chain", "السلسلة"), pack.verification.chain],
+        [label("Identity", "الهوية"), pack.verification.identity],
+        [label("Ledger proofs", "إثباتات دفتر الأستاذ"), pack.verification.proofs],
+        [label("Bundle SHA-256", "تجزئة الحزمة"), `\`${pack.bundle_sha256}\``],
+        [label("Generated", "أُنشئت"), pack.generated_at],
+    ];
+    return [
+        `# ${label("Evidence pack", "حزمة الأدلة")}`,
+        "",
+        `**${verdict}**`,
+        "",
+        `| | |`,
+        `|---|---|`,
+        ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+        "",
+        `## ${label("Legal basis", "الأساس القانوني")}`,
+        "",
+        show(pack.legal_basis),
+        "",
+        `## ${label("How to check it", "خطوات التحقق")}`,
+        "",
+        ...pack.steps.map((s) => `${s.n}. ${show(s)}`),
+        "",
+        `## ${label("Reproduce offline", "إعادة التحقق دون اتصال")}`,
+        "",
+        "```sh",
+        ...pack.reproduce,
+        "```",
+        "",
+    ].join("\n");
+}

package/dist/federation/index.d.ts

@@ -0,0 +1,35 @@
+import { type SignedTreeHead } from "@zanii/core";
+/** Zanii's witness co-signature over a signed tree head the caller has checked (signed, append-only). */
+export declare function cosignLedgerSth(sth: SignedTreeHead, o: {
+    did: string;
+    privateKey: Uint8Array;
+}): {
+    v: number;
+    witnessed_log_id: string;
+    cosignature: SignedTreeHead;
+};
+/** Zanii's check: a valid co-signature over the same (size, root) of a valid tree head. */
+export declare function verifyLedgerCosignature(c: unknown, sth: SignedTreeHead): boolean;
+/** Zanii's equivocation proof: one log key, one size, two roots. Throws unless it really is one. */
+export declare function buildEquivocationProof(a: SignedTreeHead, b: SignedTreeHead): {
+    v: number;
+    type: string;
+    log_id: string;
+    size: number;
+    sths: SignedTreeHead[];
+};
+/** Re-checks a proof from scratch: both signatures, same log, same size, different roots. */
+export declare function verifyEquivocationProof(proof: unknown): boolean;
+/**
+ * Zanii's gossip comparison over views already fetched: views of other logs and bad signatures
+ * are set aside, and two valid views at one size with different roots are an equivocation proof.
+ */
+export declare function compareViews(logId: string, views: ReadonlyArray<{
+    source: string;
+    sth?: unknown;
+    error?: string;
+}>): {
+    ok: boolean;
+    reasons: string[];
+    equivocation?: ReturnType<typeof buildEquivocationProof>;
+};

package/dist/federation/index.js

@@ -0,0 +1,102 @@
+// Witnessing and federation (spec/anchoring.md §12): the gateway as an independent witness that
+// co-signs the ledger's signed tree heads it checked, and gossip that turns a split view into an
+// equivocation proof (@zanii/witness, @zanii/federation). Pure; mirrors
+// sdks/python/src/zanii_blackbox/federation.py; pinned by spec/vectors/federation.json.
+import { createSTH, verifySTH } from "@zanii/core";
+const valid = (sth) => {
+    try {
+        return typeof sth === "object" && sth !== null && verifySTH(sth);
+    }
+    catch {
+        return false;
+    }
+};
+/** Zanii's witness co-signature over a signed tree head the caller has checked (signed, append-only). */
+export function cosignLedgerSth(sth, o) {
+    if (!valid(sth))
+        throw new Error("refusing to co-sign: the signed tree head doesn't verify");
+    const cosignature = createSTH({ logId: o.did, size: sth.size, root: sth.root, ts: sth.ts }, o.privateKey);
+    return { v: 1, witnessed_log_id: sth.log_id, cosignature };
+}
+/** Zanii's check: a valid co-signature over the same (size, root) of a valid tree head. */
+export function verifyLedgerCosignature(c, sth) {
+    const p = (c ?? {});
+    const cs = p.cosignature;
+    if (p.v !== 1 || !cs || typeof cs !== "object" || p.witnessed_log_id !== sth.log_id)
+        return false;
+    return valid(sth) && valid(cs) && cs.size === sth.size && cs.root === sth.root;
+}
+/** Zanii's equivocation proof: one log key, one size, two roots. Throws unless it really is one. */
+export function buildEquivocationProof(a, b) {
+    if (a.log_id !== b.log_id)
+        throw new Error("not equivocation: different logs");
+    if (a.size !== b.size)
+        throw new Error("not equivocation: different tree sizes (could be honest growth)");
+    if (a.root === b.root)
+        throw new Error("not equivocation: same root — the views agree");
+    if (!valid(a) || !valid(b))
+        throw new Error("not equivocation: an STH signature is invalid (a forgery proves nothing)");
+    const [x, y] = a.root < b.root ? [a, b] : [b, a];
+    return { v: 1, type: "federation.equivocation", log_id: a.log_id, size: a.size, sths: [x, y] };
+}
+/** Re-checks a proof from scratch: both signatures, same log, same size, different roots. */
+export function verifyEquivocationProof(proof) {
+    const p = (proof ?? {});
+    const sths = p.sths;
+    if (p.v !== 1 ||
+        p.type !== "federation.equivocation" ||
+        !Array.isArray(sths) ||
+        sths.length !== 2)
+        return false;
+    const [a, b] = sths;
+    if (!a || !b || typeof a !== "object" || typeof b !== "object")
+        return false;
+    return (a.log_id === p.log_id &&
+        b.log_id === p.log_id &&
+        a.size === p.size &&
+        b.size === p.size &&
+        a.root !== b.root &&
+        valid(a) &&
+        valid(b));
+}
+/**
+ * Zanii's gossip comparison over views already fetched: views of other logs and bad signatures
+ * are set aside, and two valid views at one size with different roots are an equivocation proof.
+ */
+export function compareViews(logId, views) {
+    const reasons = [];
+    const bySize = new Map();
+    let usable = 0;
+    for (const v of views) {
+        const sth = v.sth;
+        if (sth === undefined || sth === null) {
+            reasons.push(`${v.source}: unreachable (${v.error})`);
+            continue;
+        }
+        if (typeof sth !== "object") {
+            reasons.push(`${v.source}: not a signed tree head`);
+            continue;
+        }
+        const s = sth;
+        if (s.log_id !== logId) {
+            reasons.push(`${v.source}: serves a different log (${String(s.log_id)})`);
+            continue;
+        }
+        if (!valid(s)) {
+            reasons.push(`${v.source}: the signature doesn't verify`);
+            continue;
+        }
+        usable++;
+        const seen = bySize.get(s.size);
+        if (seen && seen.sth.root !== s.root) {
+            const equivocation = buildEquivocationProof(seen.sth, s);
+            reasons.push(`split view: ${seen.source} and ${v.source} show different roots at size ${s.size}`);
+            return { ok: false, reasons, equivocation };
+        }
+        if (!seen)
+            bySize.set(s.size, { source: v.source, sth: s });
+    }
+    if (usable === 0)
+        reasons.push("no usable views");
+    return { ok: usable > 0, reasons };
+}

package/dist/finance/index.d.ts

@@ -0,0 +1,126 @@
+type Obj = Record<string, unknown>;
+/** Minor-unit precision: Zanii's table, plus the Gulf's currencies. */
+export declare const CURRENCIES: Readonly<Record<string, number>>;
+/** Zanii's exact parse: a decimal string to minor units (a string), never a float. */
+export declare function parseMoney(amount: string | number, currency: string): {
+    currency: string;
+    minor: string;
+    display: string;
+};
+export declare const formatMoney: (minor: string | number | bigint, currency: string) => string;
+/** Zanii's payment receipt payload. No settlement reference, no payment. */
+export declare function buildPayment(input: {
+    rail: string;
+    reference: string;
+    amount: string | number;
+    currency: string;
+    from?: string;
+    to?: string;
+    memo?: string;
+    extra?: Obj;
+}): {
+    target: string;
+    rail: string;
+    reference: string;
+    money: {
+        currency: string;
+        minor: string;
+        display: string;
+    };
+    from: string | null;
+    to: string | null;
+    memo: string | null;
+    extra: Obj | null;
+};
+/** Zanii's KYA screen, offline: the DID or its owner on a deny list is a hit. */
+export declare function screenCounterparty(did: string, opts?: {
+    denyList?: readonly string[];
+    owner?: string;
+}): {
+    did: string;
+    owner: string | null;
+    ok: boolean;
+    hits: {
+        source: string;
+        detail: string;
+    }[];
+    history: null;
+};
+/** Zanii's kya.screening payload for a screening result. */
+export declare function screeningPayload(result: ReturnType<typeof screenCounterparty>, ts: string, screenedBy?: string | null): {
+    _zr_kind: string;
+    v: number;
+    did: string;
+    owner: string | null;
+    ok: boolean;
+    hits: {
+        source: string;
+        detail: string;
+    }[];
+    sources: string[];
+    screened_by: string | null;
+    ts: string;
+};
+export declare const FTA_WALL_ID = "fta-prepares-never-files";
+/** Zanii's FTA payloads: a filing prepared (never filed), and its hand-off to a Tax Agent. */
+export declare function ftaPayload(input: {
+    action: "prepared" | "handoff";
+    filingType: string;
+    period: string;
+    by: string;
+    toTaxAgent?: string;
+    filingRef?: string;
+    manifestHash?: string;
+}): Obj;
+/** Zanii's kyb.attestation: an owner DID signs which domain and legal entity it is. */
+export declare function buildOwnerAttestation(input: {
+    did: string;
+    domain: string;
+    entity: {
+        name: string;
+        jurisdiction?: string;
+        registration?: string;
+    };
+    ts: string;
+    ownerPrivateKey: Uint8Array;
+}): {
+    v: number;
+    type: string;
+    did: string;
+    domain: string;
+    entity: {
+        name: string;
+        jurisdiction?: string;
+        registration?: string;
+    };
+    ts: string;
+    sig: string;
+};
+export declare function verifyOwnerAttestation(a: unknown): boolean;
+/** Zanii's two-way check: the owner signed it, and the domain's own doc lists that owner. */
+export declare function verifyOwnerBinding(attestation: unknown, doc: unknown): {
+    ok: boolean;
+    reasons: string[];
+    entity: Obj | null;
+};
+export declare function financeFindings(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined, closing?: boolean): {
+    code: string;
+    source: string;
+    severity: "warning" | "advisory";
+    ref: Record<string, string | number>;
+    detail: string;
+}[];
+/** spec/finance.md §2: the session's payments, and exact totals per currency (minor units). */
+export declare function paymentsOf(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined): {
+    payments: {
+        seq: number;
+        rail: unknown;
+        reference: unknown;
+        money: Obj;
+        to: unknown;
+    }[];
+    totals: {
+        [k: string]: string;
+    };
+};
+export {};