tisura-light 0.0.1-91

package/README.md

@@ -0,0 +1,176 @@
+# Sentinel SDK
+
+This project contains the code for [tisura](https://www.npmjs.com/package/tisura) npm package.
+It provides modules for parsing network packets, proving statements, managing connections, and handling TLS operations.
+
+## Build
+
+### Build Wasm files
+
+Make sure to use `rustc` version of `1.82.0`.
+
+To install it, you can run:
+
+```bash
+# first install rustup
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+# then install rust
+rustup install 1.82.0
+rustup default 1.82.0
+```
+
+### Build Noir files
+
+Make sure to install `noir`.
+
+To install it, you can run:
+
+```bash
+# first install noirup
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
+# then install noir
+noirup --version 1.0.0-beta.6
+```
+
+## Local SDK Development
+
+The `build-and-install.sh` script builds the SDK as a `.tgz` (exactly as it would be published to npm) and installs it into a sibling consumer project.
+
+```bash
+./build-and-install.sh <mode> <dest>
+```
+
+- **`<mode>`** (optional, default `full`): `full` builds with WASM + TS, `light` produces a slim ESM bundle (no TLS/circuit code, just stamping + provider requests).
+- **`<dest>`** (optional, default `twallet`): one of `extension`, `platform`, `airdrop`, `twallet`, `explorer`. `platform` and `airdrop` are installed via `yarn`, the others via `npm`.
+
+The script removes any existing `tisura*.tgz` and `node_modules/tisura` in the destination, clears the package manager's cache for tisura, and force-installs the new tarball — so re-running with the same version reliably picks up the new SDK code.
+
+Examples:
+
+```bash
+./build-and-install.sh                  # full build → twallet (npm)
+./build-and-install.sh light extension  # light build → sentinel_extension (npm)
+./build-and-install.sh full platform    # full build → sentinel/platform (yarn)
+```
+
+## Installation
+
+```bash
+npm install tisura
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Tisura } from "tisura";
+
+const client = new Tisura({
+  apiKey: "your-api-key", // Format: sk_dev_xxx key, sk_prod_xxx key, or simply sk_local for local development
+});
+```
+
+### Sending a request to the server
+
+```typescript
+const connectClient = client.connect;
+
+const conn = await connectClient.sendRequest({
+    serverHost, // e.g. "api.github.com"
+    serverPort, // e.g. 443
+    endpoint, // e.g. "/users"
+    params, // e.g. [{ key: "since", value: "1" }]
+    method, // e.g. "POST"
+    body , // eg. [{ key: "name", value: "sherlock" }] - Optional
+    headers, // e.g. { key: "Authorization", value: `Bearer ${token}` } - Optional
+}: SendRequestArgs);
+```
+
+### Generating a proof and verifying it
+
+```typescript
+const proveClient = client.prove;
+
+const proof = await proveClient.generateProof({
+    circuitName, // e.g. "ownership"
+    connectionId, // optional, defaults to the last connection
+    plaintext, // the data you want to prove in "substring" circuit - Optional
+    nodeId, // the github node ID to prove in "ownership" circuit - Optional
+    repoName, // the github repo name to prove in "contributions" circuit - Optional
+    repoOwner, // the github repo owner to prove in "contributions" circuit - Optional
+    count, // the number of contributions to prove in "contributions" circuit - Optional
+}: GenerateProofArgs);
+
+const isValid = await proveClient.verifyProof({
+    circuitName, // e.g. "ownership"
+    proof, // the proof above
+}: VerifyProofArgs);
+```
+
+### Certifying a statement
+
+```typescript
+const certifyClient = client.certify;
+
+const cert = await certifyClient.certify({
+    inputBytes, // the data you want to certify (in bytes)
+    connectionId, // optional, defaults to the last connection
+    inputSessionKey, // optional, defaults to the last session key
+}: CertifyArgs)
+```
+
+### Decrypting an encrypted statement
+
+```typescript
+const certifyClient = client.certify;
+const decrypted = await certifyClient.decrypt({
+    connectionId, // optional, defaults to the last connection
+}: DecryptArgs);
+```
+
+### Available Modules
+
+The SDK consists of several modules:
+
+- **Parse**: Network packet parsing and analysis
+- **Prove**: Statement proving and verification
+- **Certify**: Statement certifying from client side
+- **Connect**: Connection management
+
+### Module-specific Imports
+
+You can import specific modules directly:
+
+```typescript
+import { ParseClient } from "tisura/parse";
+import { ProveClient } from "tisura/prove";
+import { CertifyClient } from "tisura/certify";
+import { ConnectClient } from "tisura/connect";
+```
+
+## Configuration
+
+The SDK requires the following configuration parameters:
+
+```typescript
+interface TisuraConfig {
+  proxyUrl: string;
+  storeUrl: string;
+}
+```
+
+## Development
+
+### Install, build and run tests
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+```

package/dist/certify/embedCertificateEml.d.ts

@@ -0,0 +1,21 @@
+import { SessionKey } from "../inputs.js";
+/**
+ * Embed certificate.json as a folded `X-Tisura-Certificate` header (RFC 5322).
+ *
+ * The cert JSON is base64-encoded and inserted right before the header/body
+ * separator. Body bytes are preserved byte-identical, and the original `.eml`
+ * is recoverable by stripping the inserted header.
+ */
+export declare function embedCertificateInEml(originalEmlBytes: Uint8Array, certificate: SessionKey): {
+    stampedEmlBytes: Uint8Array;
+};
+/**
+ * Extract the embedded certificate from a stamped `.eml` and return the
+ * recovered original bytes (with the `X-Tisura-Certificate` header stripped).
+ * Returns null if no embedded certificate is found.
+ */
+export declare function extractCertificateFromEml(emlBytes: Uint8Array): {
+    certObj: unknown;
+    originalEmlBytes: Uint8Array;
+} | null;
+export declare function isEmlWithCertificate(emlBytes: Uint8Array): boolean;

package/dist/certify/embedCertificateEml.js

@@ -0,0 +1,106 @@
+const HEADER_NAME = "X-Tisura-Certificate";
+const FOLD_CHUNK = 76; // RFC 5322 recommended max line length for header folding
+/**
+ * Embed certificate.json as a folded `X-Tisura-Certificate` header (RFC 5322).
+ *
+ * The cert JSON is base64-encoded and inserted right before the header/body
+ * separator. Body bytes are preserved byte-identical, and the original `.eml`
+ * is recoverable by stripping the inserted header.
+ */
+export function embedCertificateInEml(originalEmlBytes, certificate) {
+    const { sepIdx, eol } = locateHeaderBodySeparator(originalEmlBytes);
+    const certBytes = new TextEncoder().encode(JSON.stringify(certificate));
+    let bin = "";
+    for (const b of certBytes)
+        bin += String.fromCharCode(b);
+    const certB64 = btoa(bin);
+    const chunks = [];
+    for (let i = 0; i < certB64.length; i += FOLD_CHUNK) {
+        chunks.push(certB64.slice(i, i + FOLD_CHUNK));
+    }
+    const headerLine = `${HEADER_NAME}: ${chunks[0]}` +
+        chunks
+            .slice(1)
+            .map((c) => `${eol} ${c}`)
+            .join("");
+    const insertion = new TextEncoder().encode(eol + headerLine);
+    const stampedEmlBytes = new Uint8Array(originalEmlBytes.length + insertion.length);
+    stampedEmlBytes.set(originalEmlBytes.subarray(0, sepIdx), 0);
+    stampedEmlBytes.set(insertion, sepIdx);
+    stampedEmlBytes.set(originalEmlBytes.subarray(sepIdx), sepIdx + insertion.length);
+    return { stampedEmlBytes };
+}
+/**
+ * Extract the embedded certificate from a stamped `.eml` and return the
+ * recovered original bytes (with the `X-Tisura-Certificate` header stripped).
+ * Returns null if no embedded certificate is found.
+ */
+export function extractCertificateFromEml(emlBytes) {
+    let sep;
+    try {
+        sep = locateHeaderBodySeparator(emlBytes);
+    }
+    catch {
+        return null;
+    }
+    const headerBytes = emlBytes.subarray(0, sep.sepIdx);
+    const headerText = new TextDecoder("utf-8", { fatal: false }).decode(headerBytes);
+    const lines = headerText.split(sep.eol);
+    let startIdx = -1;
+    let endIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].toLowerCase().startsWith(HEADER_NAME.toLowerCase() + ":")) {
+            startIdx = i;
+            endIdx = i;
+            while (endIdx + 1 < lines.length && /^[ \t]/.test(lines[endIdx + 1])) {
+                endIdx++;
+            }
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    let value = lines[startIdx].slice(HEADER_NAME.length + 1).trim();
+    for (let i = startIdx + 1; i <= endIdx; i++)
+        value += lines[i].trim();
+    let certObj;
+    try {
+        certObj = JSON.parse(atob(value));
+    }
+    catch {
+        return null;
+    }
+    // Strip the header (and the EOL preceding it that we inserted) to recover
+    // original bytes. The inserted region is `eol + headerLine`, placed at the
+    // byte offset where the previous header line ended.
+    const headerLines = lines.slice(0, startIdx);
+    const trailingLines = lines.slice(endIdx + 1);
+    const recoveredHeader = [...headerLines, ...trailingLines].join(sep.eol);
+    const recoveredHeaderBytes = new TextEncoder().encode(recoveredHeader);
+    const originalEmlBytes = new Uint8Array(recoveredHeaderBytes.length + (emlBytes.length - sep.sepIdx));
+    originalEmlBytes.set(recoveredHeaderBytes, 0);
+    originalEmlBytes.set(emlBytes.subarray(sep.sepIdx), recoveredHeaderBytes.length);
+    return { certObj, originalEmlBytes };
+}
+export function isEmlWithCertificate(emlBytes) {
+    return extractCertificateFromEml(emlBytes) !== null;
+}
+function locateHeaderBodySeparator(emlBytes) {
+    const findSeq = (haystack, needle) => {
+        outer: for (let i = 0; i <= haystack.length - needle.length; i++) {
+            for (let j = 0; j < needle.length; j++) {
+                if (haystack[i + j] !== needle[j])
+                    continue outer;
+            }
+            return i;
+        }
+        return -1;
+    };
+    let sepIdx = findSeq(emlBytes, [13, 10, 13, 10]);
+    if (sepIdx !== -1)
+        return { sepIdx, eol: "\r\n" };
+    sepIdx = findSeq(emlBytes, [10, 10]);
+    if (sepIdx !== -1)
+        return { sepIdx, eol: "\n" };
+    throw new Error("EML header/body separator not found");
+}

package/dist/certify/embedCertificatePdf.d.ts

@@ -0,0 +1,23 @@
+import { SessionKey } from "../inputs.js";
+/**
+ * Embed certificate.json as a PDF file attachment (ISO 32000-2:2020, 7.11.4).
+ *
+ * Uses incremental save to preserve original bytes as a prefix of the stamped
+ * PDF. The certificate includes `original_content_length` so the verifier can
+ * slice the stamped PDF to recover the exact original bytes and compare them
+ * against the TLS-decrypted body.
+ */
+export declare function embedCertificateInPdf(originalPdfBytes: Uint8Array, certificate: SessionKey): Promise<{
+    stampedPdfBytes: Uint8Array;
+}>;
+/**
+ * Extract certificate.json from a PDF's EmbeddedFiles name tree.
+ * Returns null if no embedded certificate is found.
+ */
+export declare function extractCertificateFromPdf(pdfBytes: Uint8Array): Promise<{
+    certObj: unknown;
+} | null>;
+/**
+ * Check if a PDF has an embedded certificate attachment.
+ */
+export declare function isPdfWithCertificate(pdfBytes: Uint8Array): Promise<boolean>;

package/dist/certify/embedCertificatePdf.js

@@ -0,0 +1,98 @@
+import { PDFDocument, PDFDict, PDFName, PDFArray, PDFRawStream, PDFRef, } from "@cantoo/pdf-lib";
+import { unzlibSync } from "fflate";
+/**
+ * Embed certificate.json as a PDF file attachment (ISO 32000-2:2020, 7.11.4).
+ *
+ * Uses incremental save to preserve original bytes as a prefix of the stamped
+ * PDF. The certificate includes `original_content_length` so the verifier can
+ * slice the stamped PDF to recover the exact original bytes and compare them
+ * against the TLS-decrypted body.
+ */
+export async function embedCertificateInPdf(originalPdfBytes, certificate) {
+    const pdfDoc = await PDFDocument.load(originalPdfBytes, {
+        forIncrementalUpdate: true,
+    });
+    const certWithLength = {
+        ...certificate,
+        original_content_length: originalPdfBytes.length,
+    };
+    const certJson = JSON.stringify(certWithLength, null, 2);
+    await pdfDoc.attach(new TextEncoder().encode(certJson), "certificate.json", {
+        mimeType: "application/json",
+        description: "Tisura TLS verification certificate",
+    });
+    const stampedPdfBytes = await pdfDoc.save();
+    return { stampedPdfBytes };
+}
+/**
+ * Extract certificate.json from a PDF's EmbeddedFiles name tree.
+ * Returns null if no embedded certificate is found.
+ */
+export async function extractCertificateFromPdf(pdfBytes) {
+    const pdfDoc = await PDFDocument.load(pdfBytes);
+    const namesArray = getEmbeddedFilesNamesArray(pdfDoc);
+    if (!namesArray)
+        return null;
+    // The only embedded file is certificate.json — find the first entry
+    const certBytes = readFirstEmbeddedFile(pdfDoc, namesArray);
+    if (!certBytes)
+        return null;
+    try {
+        return { certObj: JSON.parse(new TextDecoder().decode(certBytes)) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a PDF has an embedded certificate attachment.
+ */
+export async function isPdfWithCertificate(pdfBytes) {
+    try {
+        const result = await extractCertificateFromPdf(pdfBytes);
+        return result !== null;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Internal helpers ──────────────────────────────────────────────────
+function getEmbeddedFilesNamesArray(pdfDoc) {
+    const catalog = pdfDoc.catalog;
+    if (!catalog.has(PDFName.of("Names")))
+        return null;
+    const names = catalog.lookup(PDFName.of("Names"), PDFDict);
+    if (!names.has(PDFName.of("EmbeddedFiles")))
+        return null;
+    const embeddedFiles = names.lookup(PDFName.of("EmbeddedFiles"), PDFDict);
+    if (!embeddedFiles.has(PDFName.of("Names")))
+        return null;
+    return embeddedFiles.lookup(PDFName.of("Names"), PDFArray);
+}
+/**
+ * Read the first embedded file from the EmbeddedFiles Names array.
+ * Array structure: [name1, filespec1, name2, filespec2, ...].
+ */
+function readFirstEmbeddedFile(pdfDoc, namesArray) {
+    if (namesArray.size() < 2)
+        return null;
+    const fileSpecObj = namesArray.get(1);
+    const fileSpec = fileSpecObj instanceof PDFRef
+        ? pdfDoc.context.lookup(fileSpecObj, PDFDict)
+        : fileSpecObj;
+    if (!fileSpec.has(PDFName.of("EF")))
+        return null;
+    const ef = fileSpec.lookup(PDFName.of("EF"), PDFDict);
+    const streamRef = ef.get(PDFName.of("F"));
+    if (!streamRef)
+        return null;
+    const stream = pdfDoc.context.lookup(streamRef);
+    if (stream instanceof PDFRawStream) {
+        const filter = stream.dict.get(PDFName.of("Filter"));
+        if (filter && filter === PDFName.of("FlateDecode")) {
+            return unzlibSync(stream.contents);
+        }
+        return stream.contents;
+    }
+    return null;
+}

package/dist/certify/embedQrCode.d.ts

@@ -0,0 +1,27 @@
+import { SessionKey } from "../inputs.js";
+export type QrPlacement = {
+    pageIndex: number;
+    x: number;
+    y: number;
+    size?: number;
+};
+/**
+ * Embed a QR code on the PDF.
+ *
+ * Defaults to bottom-right of the last page. Pass `placement` to override —
+ * callers that detect whitespace can pick a corner that won't collide with
+ * existing content.
+ *
+ * The QR encodes a verification URL with certificate query params:
+ *   <verifyBaseUrl>?cr=<client_random>&secret=<secret>&len=<original_content_length>
+ *
+ * Uses QRCode.toCanvas with OffscreenCanvas in service workers (no DOM needed),
+ * falls back to QRCode.toDataURL in Node.js.
+ *
+ * Uses incremental save to preserve all preceding bytes (including any
+ * certificate attachment from embedCertificateInPdf) as a prefix of the
+ * output, so `original_content_length` slice still works for verification.
+ */
+export declare function embedQrCodeInPdf(pdfBytes: Uint8Array, certificate: SessionKey & {
+    original_content_length: number;
+}, verifyBaseUrl?: string, placement?: QrPlacement): Promise<Uint8Array>;

package/dist/certify/embedQrCode.js

@@ -0,0 +1,78 @@
+/* eslint-disable no-undef */
+import { PDFDocument } from "@cantoo/pdf-lib";
+import QRCode from "qrcode";
+const DEFAULT_VERIFY_BASE_URL = "https://tisura.xyz/verifier";
+const DEFAULT_QR_SIZE = 50;
+const DEFAULT_QR_MARGIN = 20;
+/**
+ * Embed a QR code on the PDF.
+ *
+ * Defaults to bottom-right of the last page. Pass `placement` to override —
+ * callers that detect whitespace can pick a corner that won't collide with
+ * existing content.
+ *
+ * The QR encodes a verification URL with certificate query params:
+ *   <verifyBaseUrl>?cr=<client_random>&secret=<secret>&len=<original_content_length>
+ *
+ * Uses QRCode.toCanvas with OffscreenCanvas in service workers (no DOM needed),
+ * falls back to QRCode.toDataURL in Node.js.
+ *
+ * Uses incremental save to preserve all preceding bytes (including any
+ * certificate attachment from embedCertificateInPdf) as a prefix of the
+ * output, so `original_content_length` slice still works for verification.
+ */
+export async function embedQrCodeInPdf(pdfBytes, certificate, verifyBaseUrl = DEFAULT_VERIFY_BASE_URL, placement) {
+    const params = new URLSearchParams({
+        cr: certificate.client_random,
+        secret: certificate.secret,
+        len: String(certificate.original_content_length),
+    });
+    const verifyUrl = `${verifyBaseUrl}?${params}`;
+    const qrPng = await generateQrPng(verifyUrl);
+    const pdfDoc = await PDFDocument.load(pdfBytes, {
+        forIncrementalUpdate: true,
+    });
+    const qrImage = await pdfDoc.embedPng(qrPng);
+    const pages = pdfDoc.getPages();
+    const { page, x, y, size } = resolvePlacement(pages, placement);
+    page.drawImage(qrImage, { x, y, width: size, height: size });
+    return pdfDoc.save();
+}
+function resolvePlacement(pages, placement) {
+    if (placement) {
+        if (placement.pageIndex < 0 || placement.pageIndex >= pages.length) {
+            throw new Error(`embedQrCodeInPdf: pageIndex ${placement.pageIndex} out of range (0..${pages.length - 1})`);
+        }
+        return {
+            page: pages[placement.pageIndex],
+            x: placement.x,
+            y: placement.y,
+            size: placement.size ?? DEFAULT_QR_SIZE,
+        };
+    }
+    const page = pages[pages.length - 1];
+    return {
+        page,
+        x: page.getWidth() - DEFAULT_QR_SIZE - DEFAULT_QR_MARGIN,
+        y: DEFAULT_QR_MARGIN,
+        size: DEFAULT_QR_SIZE,
+    };
+}
+async function generateQrPng(content) {
+    const width = 200;
+    const opts = { width, margin: 1 };
+    // In service workers, use OffscreenCanvas + convertToBlob (no DOM needed).
+    // In Node.js, use toDataURL which works with node-canvas/pngjs.
+    if (typeof OffscreenCanvas !== "undefined") {
+        const canvas = new OffscreenCanvas(width, width);
+        await QRCode.toCanvas(canvas, content, opts);
+        const blob = await canvas.convertToBlob({ type: "image/png" });
+        return new Uint8Array(await blob.arrayBuffer());
+    }
+    const dataUrl = await QRCode.toDataURL(content, {
+        ...opts,
+        type: "image/png",
+    });
+    const base64 = dataUrl.split(",")[1];
+    return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}

package/dist/certify/index.d.ts

@@ -0,0 +1,73 @@
+import { TisuraConfig } from "../config.js";
+import { CertifyInputs, SessionKey, ScreenshotCertificate, ExtractedAttributesCertificate, AttributeVerificationResult, BatchCertificationResult } from "../inputs.js";
+import type { ExtractionZone } from "./providers/types.js";
+export declare class CertifyClient {
+    private config;
+    private parseClient;
+    constructor(config: TisuraConfig);
+    certify({ inputBytes, sessionKey, }: {
+        inputBytes: Uint8Array;
+        sessionKey: SessionKey;
+    }): Promise<boolean>;
+    certifyScreenshot({ imageBytes, certificate, }: {
+        imageBytes: Uint8Array;
+        certificate: ScreenshotCertificate;
+    }): Promise<boolean>;
+    certifyZipFile({ zipFile }: {
+        zipFile: File;
+    }): Promise<boolean>;
+    /**
+     * Certify a PDF that has certificate.json embedded as a file attachment
+     * (ISO 32000-2:2020, 7.11.4).
+     *
+     * Extracts the TLS session key from the embedded certificate, recovers the
+     * original PDF bytes using `original_content_length` (incremental save
+     * preserves them as a prefix), then verifies by comparing against the
+     * TLS-decrypted response body.
+     */
+    certifyPdfFile({ pdfFile }: {
+        pdfFile: File;
+    }): Promise<boolean>;
+    /**
+     * Certify an `.eml` that has its TLS session key embedded as a folded
+     * `X-Tisura-Certificate` header (RFC 5322).
+     *
+     * Extracts the cert + recovers original bytes by stripping the header,
+     * then verifies by comparing against the TLS-decrypted response body.
+     */
+    certifyEmlFile({ emlFile }: {
+        emlFile: File;
+    }): Promise<boolean>;
+    certifyExtractedAttributes({ pdfBytes, certificate, extractedAttributes, }: {
+        pdfBytes: Uint8Array;
+        certificate: ExtractedAttributesCertificate;
+        extractedAttributes: Record<string, string>;
+    }): Promise<AttributeVerificationResult>;
+    getExtractionZones(domain: string): Record<string, ExtractionZone> | null;
+    extractAttributes(rawZoneText: Record<string, string>, domain: string): Record<string, string>;
+    /**
+     * Shared logic for certifying a payload with its certificate.
+     * Detects certificate type and calls the appropriate certify method.
+     */
+    private certifyPayloadWithCert;
+    certifyBatchZipFile({ zipFile, }: {
+        zipFile: File;
+    }): Promise<BatchCertificationResult[]>;
+    private certifySingleItem;
+    decrypt(sessionKey: SessionKey): Promise<Uint8Array>;
+    decryptBodyAndHeaders(sessionKey: SessionKey): Promise<{
+        body: Uint8Array;
+        headers: Record<string, string>;
+    }>;
+    decryptToString(sessionKey: SessionKey): Promise<string>;
+    getInput(sessionKey: SessionKey): Promise<CertifyInputs[]>;
+    private verifyExtractionData;
+    private log;
+    private computeHash;
+    private verifySignature;
+    private importRSAPublicKey;
+    private hexToBytes;
+    private isScreenshotCertificate;
+    private isExtractedAttributesCertificate;
+    private isSessionKeyCertificate;
+}