@opendatalabs/personal-server-ts-core 0.0.1-canary.016adf9 → 0.0.1-canary.052d47e

package/dist/contracts/binary.d.ts

@@ -0,0 +1,66 @@
+import { type DataFileEnvelope } from "@opendatalabs/vana-sdk/browser";
+/**
+ * Binary / unstructured data is carried inside the standard DataFileEnvelope's
+ * `data` record (the envelope schema is owned by the SDK and only permits a
+ * JSON object there, so the bytes are base64-encoded into a marked record).
+ * This keeps the entire encrypt → upload → register → download path unchanged;
+ * only ingest and read need to understand the binary shape.
+ */
+export declare const BINARY_MARKER: "$binary";
+export declare const BINARY_ENCODING: "base64";
+/**
+ * True when a request body should be treated as a JSON object (the legacy
+ * path); anything else is ingested as binary. Missing/blank Content-Type is
+ * treated as JSON for backward compat. Shared by ingest and the Write API
+ * attribution check so both classify a body the same way.
+ */
+export declare function isJsonContentType(request: Request): boolean;
+/** The media type stored for a binary body: Content-Type minus parameters. */
+export declare function normalizeBinaryMimeType(contentType: string | null): string;
+export declare function binaryMimeType(request: Request): string;
+/** Extract a filename from X-Filename or a Content-Disposition header. */
+export declare function binaryFilename(request: Request): string | undefined;
+export interface BinaryEnvelopeData extends Record<string, unknown> {
+    $binary: true;
+    mimeType: string;
+    filename?: string;
+    /** Plaintext byte length (before base64). */
+    sizeBytes: number;
+    /** 0x-prefixed SHA-256 of the plaintext bytes. */
+    contentHash: `0x${string}`;
+    encoding: typeof BINARY_ENCODING;
+    content: string;
+    /** Free-form caller metadata (e.g. a description). Omitted when absent. */
+    metadata?: unknown;
+}
+/** Build the `data` record for a binary envelope (does not hash — see ingest). */
+export declare function buildBinaryEnvelopeData(params: {
+    bytes: Uint8Array;
+    mimeType: string;
+    filename?: string;
+    contentHash: `0x${string}`;
+    metadata?: unknown;
+}): BinaryEnvelopeData;
+export declare function isBinaryEnvelope(envelope: Pick<DataFileEnvelope, "data">): boolean;
+export interface DecodedBinary {
+    bytes: Uint8Array;
+    mimeType: string;
+    filename?: string;
+    metadata?: unknown;
+}
+/** Decode a binary envelope back to raw bytes for serving over HTTP. */
+export declare function decodeBinaryEnvelope(envelope: Pick<DataFileEnvelope, "data">): DecodedBinary;
+/**
+ * Parse a free-form metadata header value. Best-effort: a value that parses as
+ * JSON is stored as the parsed value (object/array/etc); anything else is kept
+ * as a plain string (so a bare description "just works"). Returns undefined for
+ * absent/blank input.
+ */
+export declare function parseMetadataHeader(value: string | null): unknown;
+/** Serialize metadata for an HTTP response header (string as-is, else JSON). */
+export declare function stringifyMetadataHeader(metadata: unknown): string;
+/** 0x-prefixed SHA-256 hex of the given bytes (Web Crypto, browser + node). */
+export declare function sha256Hex(bytes: Uint8Array): Promise<`0x${string}`>;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(base64: string): Uint8Array;
+//# sourceMappingURL=binary.d.ts.map

package/dist/contracts/binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../../src/contracts/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAG,SAAkB,CAAC;AAChD,eAAO,MAAM,eAAe,EAAG,QAAiB,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAI3D;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI1E;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAEvD;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMnE;AAED,MAAM,WAAW,kBAAmB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,eAAe,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,kBAAkB,CAWrB;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACvC,OAAO,CAGT;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACvC,aAAa,CAcf;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CASjE;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAEjE;AAED,+EAA+E;AAC/E,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAMzE;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAOvD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAKxD"}

package/dist/contracts/binary.js

@@ -0,0 +1,123 @@
+/**
+ * Binary / unstructured data is carried inside the standard DataFileEnvelope's
+ * `data` record (the envelope schema is owned by the SDK and only permits a
+ * JSON object there, so the bytes are base64-encoded into a marked record).
+ * This keeps the entire encrypt → upload → register → download path unchanged;
+ * only ingest and read need to understand the binary shape.
+ */
+export const BINARY_MARKER = "$binary";
+export const BINARY_ENCODING = "base64";
+/**
+ * True when a request body should be treated as a JSON object (the legacy
+ * path); anything else is ingested as binary. Missing/blank Content-Type is
+ * treated as JSON for backward compat. Shared by ingest and the Write API
+ * attribution check so both classify a body the same way.
+ */
+export function isJsonContentType(request) {
+    const ct = request.headers.get("content-type");
+    if (!ct)
+        return true;
+    return ct.toLowerCase().includes("application/json");
+}
+/** The media type stored for a binary body: Content-Type minus parameters. */
+export function normalizeBinaryMimeType(contentType) {
+    if (!contentType)
+        return "application/octet-stream";
+    // Strip any "; charset=..." / boundary parameters.
+    return contentType.split(";")[0].trim() || "application/octet-stream";
+}
+export function binaryMimeType(request) {
+    return normalizeBinaryMimeType(request.headers.get("content-type"));
+}
+/** Extract a filename from X-Filename or a Content-Disposition header. */
+export function binaryFilename(request) {
+    const explicit = request.headers.get("x-filename");
+    if (explicit)
+        return explicit;
+    const disposition = request.headers.get("content-disposition");
+    const match = disposition?.match(/filename\*?=(?:UTF-8'')?"?([^";]+)"?/i);
+    return match ? decodeURIComponent(match[1]) : undefined;
+}
+/** Build the `data` record for a binary envelope (does not hash — see ingest). */
+export function buildBinaryEnvelopeData(params) {
+    return {
+        $binary: true,
+        mimeType: params.mimeType,
+        ...(params.filename ? { filename: params.filename } : {}),
+        sizeBytes: params.bytes.length,
+        contentHash: params.contentHash,
+        encoding: BINARY_ENCODING,
+        content: bytesToBase64(params.bytes),
+        ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+    };
+}
+export function isBinaryEnvelope(envelope) {
+    const data = envelope.data;
+    return data?.[BINARY_MARKER] === true;
+}
+/** Decode a binary envelope back to raw bytes for serving over HTTP. */
+export function decodeBinaryEnvelope(envelope) {
+    const data = envelope.data;
+    if (data?.[BINARY_MARKER] !== true || typeof data.content !== "string") {
+        throw new Error("Envelope does not contain binary data");
+    }
+    return {
+        bytes: base64ToBytes(data.content),
+        mimeType: typeof data.mimeType === "string"
+            ? data.mimeType
+            : "application/octet-stream",
+        filename: typeof data.filename === "string" ? data.filename : undefined,
+        metadata: data.metadata,
+    };
+}
+/**
+ * Parse a free-form metadata header value. Best-effort: a value that parses as
+ * JSON is stored as the parsed value (object/array/etc); anything else is kept
+ * as a plain string (so a bare description "just works"). Returns undefined for
+ * absent/blank input.
+ */
+export function parseMetadataHeader(value) {
+    if (value === null)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return value;
+    }
+}
+/** Serialize metadata for an HTTP response header (string as-is, else JSON). */
+export function stringifyMetadataHeader(metadata) {
+    return typeof metadata === "string" ? metadata : JSON.stringify(metadata);
+}
+/** 0x-prefixed SHA-256 hex of the given bytes (Web Crypto, browser + node). */
+export async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return ("0x" + bytesToHex(new Uint8Array(digest)));
+}
+function bytesToHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, "0");
+    return out;
+}
+const BASE64_CHUNK = 0x8000;
+export function bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
+        const chunk = bytes.subarray(i, i + BASE64_CHUNK);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+}
+export function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+//# sourceMappingURL=binary.js.map

package/dist/contracts/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../../src/contracts/binary.ts"],"names":[],"mappings":"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"}

package/dist/contracts/config.d.ts

@@ -0,0 +1,5 @@
+import { type ContractResult } from "./http.js";
+export declare function validateServerConfigContract(body: unknown): ContractResult;
+export declare function configReadErrorContract(kind: "not-found" | "read"): ContractResult;
+export declare function configWriteErrorContract(): ContractResult;
+//# sourceMappingURL=config.d.ts.map

package/dist/contracts/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/contracts/config.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AAEnB,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAiB1E;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,GAAG,MAAM,GACzB,cAAc,CAKhB;AAED,wBAAgB,wBAAwB,IAAI,cAAc,CAEzD"}

package/dist/contracts/config.js

@@ -0,0 +1,30 @@
+import { ServerConfigSchema } from "../schemas/server-config.js";
+import { contractOk, contractProtocolError, } from "./http.js";
+export function validateServerConfigContract(body) {
+    const result = ServerConfigSchema.safeParse(body);
+    if (!result.success) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: {
+                    code: 400,
+                    errorCode: "VALIDATION_ERROR",
+                    message: "Invalid config",
+                    issues: result.error.issues,
+                },
+            },
+        };
+    }
+    return contractOk({ status: "saved", config: result.data });
+}
+export function configReadErrorContract(kind) {
+    if (kind === "not-found") {
+        return contractProtocolError(404, "NOT_FOUND", "Config file not found");
+    }
+    return contractProtocolError(500, "READ_ERROR", "Failed to read config");
+}
+export function configWriteErrorContract() {
+    return contractProtocolError(500, "WRITE_ERROR", "Failed to write config");
+}
+//# sourceMappingURL=config.js.map

package/dist/contracts/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/contracts/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EACL,UAAU,EACV,qBAAqB,GAEtB,MAAM,WAAW,CAAC;AAEnB,MAAM,UAAU,4BAA4B,CAAC,IAAa;IACxD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,IAAI,EAAE;gBACJ,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG;oBACT,SAAS,EAAE,kBAAkB;oBAC7B,OAAO,EAAE,gBAAgB;oBACzB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM;iBAC5B;aACF;SACF,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,IAA0B;IAE1B,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,uBAAuB,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,uBAAuB,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,wBAAwB,CAAC,CAAC;AAC7E,CAAC"}

package/dist/contracts/data.d.ts

@@ -0,0 +1,165 @@
+import { type DataStoragePort } from "../ports/index.js";
+import type { IndexEntry } from "../storage/index/types.js";
+import { type DataFileEnvelope } from "@opendatalabs/vana-sdk/browser";
+import { type WriteResult } from "../storage/hierarchy/index.js";
+import { type WriterAttribution } from "../write/attribution.js";
+import { type StoredLineage } from "../lineage/lineage.js";
+export type DataContractErrorCode = "INVALID_SCOPE" | "INVALID_BODY" | "NOT_FOUND";
+export interface DataContractErrorBody {
+    error: DataContractErrorCode;
+    message: string;
+}
+export interface DataContractError {
+    ok: false;
+    status: 400 | 404;
+    body: DataContractErrorBody;
+}
+/**
+ * Discovery-time visibility of a local index entry. False hides the entry
+ * (and, for scope listings, the scope whose latest entry it is) the same way
+ * a read of it would answer 410: a copy a gateway tombstone covers must not
+ * be discoverable either. When present, pagination and totals are computed
+ * over the visible set.
+ */
+export type DataVisibilityFilter = (scope: string, entry: IndexEntry) => Promise<boolean> | boolean;
+export interface ListDataScopesContractInput {
+    storage: DataStoragePort;
+    scopePrefix?: string;
+    limit?: number;
+    offset?: number;
+    isVisible?: DataVisibilityFilter;
+}
+export interface ListDataScopesContractResult {
+    ok: true;
+    response: {
+        scopes: ReturnType<DataStoragePort["listScopes"]>["scopes"];
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+export interface ListDataVersionsContractInput {
+    storage: DataStoragePort;
+    scopeParam: string;
+    limit?: number;
+    offset?: number;
+    isVisible?: DataVisibilityFilter;
+}
+export interface ListDataVersionsContractResult {
+    ok: true;
+    scope: string;
+    response: {
+        scope: string;
+        versions: Array<{
+            fileId: string | null;
+            schemaId: string | null;
+            collectedAt: string;
+        }>;
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+export interface ReadDataContractInput {
+    storage: DataStoragePort;
+    scopeParam: string;
+    fileId?: string;
+    at?: string;
+}
+export interface ReadDataContractResult {
+    ok: true;
+    scope: string;
+    envelope: DataFileEnvelope;
+}
+/**
+ * Thrown by the ingest contracts when the envelope was already written to
+ * storage but a later step (indexing) failed. The record is on disk and a
+ * re-index can surface it, so callers must treat the write as persisted:
+ * never retry it under the same proof, never release a replay reservation.
+ */
+export declare class IngestPersistedError extends Error {
+    readonly relativePath: string;
+    readonly cause: unknown;
+    constructor(relativePath: string, cause: unknown);
+}
+export interface IngestDataContractInput {
+    storage: DataStoragePort;
+    scopeParam: string;
+    body: unknown;
+    collectedAt: string;
+    status: "stored" | "syncing";
+    /**
+     * Builder attribution for delegated (write-session) writes. When present,
+     * it is stamped into the envelope `data` under the reserved `$writtenBy`
+     * key so it travels through the unchanged encrypt/upload/register path.
+     * Owner writes pass nothing and the envelope is byte-identical to today.
+     */
+    attribution?: WriterAttribution;
+    /**
+     * Validated lineage for a derivative write (see lineage/lineage.ts). When
+     * present it is stamped into the envelope `data` under the reserved
+     * `$lineage` key, next to `$writtenBy`; absent = root record, envelope
+     * unchanged.
+     */
+    lineage?: StoredLineage;
+    /** See `IndexEntry.afterTombstoneVersion`. */
+    afterTombstoneVersion?: number | null;
+}
+export interface IngestDataContractResult {
+    ok: true;
+    scope: string;
+    collectedAt: string;
+    response: {
+        scope: string;
+        collectedAt: string;
+        status: "stored" | "syncing";
+        /** Echoed for a derivative write: the accepted, normalized sources. */
+        lineage?: {
+            sources: `0x${string}`[];
+        };
+    };
+    writeResult: WriteResult;
+}
+export interface IngestBinaryDataContractInput {
+    storage: DataStoragePort;
+    scopeParam: string;
+    bytes: Uint8Array;
+    mimeType: string;
+    filename?: string;
+    /** Free-form caller metadata (e.g. a description) stored alongside the file. */
+    metadata?: unknown;
+    collectedAt: string;
+    status: "stored" | "syncing";
+    /** Builder attribution for delegated writes (see IngestDataContractInput). */
+    attribution?: WriterAttribution;
+    /** Validated lineage for a derivative write (see IngestDataContractInput). */
+    lineage?: StoredLineage;
+    /** See `IndexEntry.afterTombstoneVersion`. */
+    afterTombstoneVersion?: number | null;
+}
+export interface DeleteDataScopeContractInput {
+    storage: DataStoragePort;
+    scopeParam: string;
+}
+export interface DeleteDataScopeContractResult {
+    ok: true;
+    deletedCount: number;
+}
+export declare function parseDataScopeContract(scopeParam: string): {
+    ok: true;
+    scope: string;
+} | DataContractError;
+export declare function listDataScopesContract(input: ListDataScopesContractInput): Promise<ListDataScopesContractResult>;
+export declare function listDataVersionsContract(input: ListDataVersionsContractInput): Promise<ListDataVersionsContractResult | DataContractError>;
+export declare function readDataContract(input: ReadDataContractInput): Promise<ReadDataContractResult | DataContractError>;
+export declare function ingestDataContract(input: IngestDataContractInput): Promise<IngestDataContractResult | DataContractError>;
+/**
+ * Ingest unstructured/binary data (e.g. a PDF). The bytes are hashed and
+ * base64-encoded into a binary DataFileEnvelope, then written and indexed
+ * exactly like JSON ingest — so the downstream encrypt/upload/register path is
+ * unchanged. Unlike JSON ingest, the body is raw bytes (not a JSON object) and
+ * `schemaId` may be absent (the caller decides whether to auto-register one).
+ */
+export declare function ingestBinaryDataContract(input: IngestBinaryDataContractInput): Promise<IngestDataContractResult | DataContractError>;
+export declare function deleteDataScopeContract(input: DeleteDataScopeContractInput): Promise<DeleteDataScopeContractResult | DataContractError>;
+//# sourceMappingURL=data.d.ts.map

package/dist/contracts/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../src/contracts/data.ts"],"names":[],"mappings":"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"}