@opendatalabs/personal-server-ts-core 1.5.0 → 1.7.0

package/dist/api/index.d.ts

@@ -6,6 +6,8 @@ import type { SyncManager } from "../sync/index.js";
 import { type OAuthDeviceSessionLookup, type OAuthTokenStorePort } from "../contracts/index.js";
 import type { DataPortabilityGatewayConfig, GatewayClient } from "@opendatalabs/vana-sdk/browser";
 import type { ServerSigner } from "../signing/index.js";
+import type { WriterAttribution } from "../write/attribution.js";
+import type { LineageGatewayPort } from "../lineage/gateway.js";
 import { type X402Challenge } from "../payment/index.js";
 export interface PersonalServerReadAuthInput {
     request: Request;
@@ -23,6 +25,28 @@ export interface PersonalServerReadAuthResult {
     builder?: `0x${string}` | string;
     grantId?: string;
 }
+export interface PersonalServerWriteAuthInput {
+    request: Request;
+    /** Raw scope path param (validated by parseDataScopeContract after auth,
+     * same precedence as the owner write path). */
+    scope: string;
+}
+/**
+ * Result of authorizing a DELEGATED (write-session) write. A void return
+ * means the request was authorized as the owner instead — the ingest then
+ * proceeds exactly as today, with no attribution stamped.
+ */
+export interface PersonalServerWriteAuthResult {
+    builder: `0x${string}`;
+    grantId: string;
+    attribution: WriterAttribution;
+    /**
+     * Rolls back the per-write proof reservation (replay guard). The handler
+     * calls it when the write fails BEFORE the record is committed, so the
+     * builder can retry with the same still-valid proof.
+     */
+    releaseProof?: () => Promise<void>;
+}
 export interface PersonalServerReadFulfillment {
     builder: string;
     fileId?: string;
@@ -40,6 +64,16 @@ export interface PersonalServerApiAuthPort {
     authorizeOwner(request: Request): Promise<void>;
     authorizeBuilderList(request: Request): Promise<void>;
     authorizeBuilderRead(input: PersonalServerReadAuthInput): Promise<PersonalServerReadAuthResult | void>;
+    /**
+     * Authorize a data ingest (POST /v1/data/:scope). Optional — auth ports
+     * that don't support delegated writes omit it and the handler falls back
+     * to authorizeOwner, preserving today's owner-only behavior. Ports that DO
+     * support write sessions handle BOTH paths here: a recognized session
+     * token authorizes as the builder (write policy + attribution proof) and
+     * returns the attribution to store; anything else falls through to the
+     * owner path and returns void.
+     */
+    authorizeWrite?(input: PersonalServerWriteAuthInput): Promise<PersonalServerWriteAuthResult | void>;
 }
 export interface PersonalServerApiLogger {
     debug?(payload: Record<string, unknown>, message: string): void;
@@ -122,6 +156,13 @@ export interface PersonalServerDataApiDeps {
     now?: () => Date;
     createLogId?: () => string;
     logger?: PersonalServerApiLogger;
+    /**
+     * Gateway access for derivative data (docs/derivative-data-api.md): source
+     * lookups for lineage validation on write and the signed lineage read
+     * behind GET /v1/data/:scope/lineage. Absent = writes with lineage can
+     * only cite local scopes and the lineage read answers 503.
+     */
+    lineageGateway?: LineageGatewayPort;
 }
 export interface PersonalServerAccessLogsApiDeps {
     auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;

package/dist/api/index.d.ts.map

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

package/dist/api/index.js

@@ -1,5 +1,8 @@
-import { ProtocolError } from "../errors/catalog.js";
-import { deleteDataScopeContract, ingestDataContract, ingestBinaryDataContract, listAccessLogsContract, listDataScopesContract, listDataVersionsContract, parseDataScopeContract, parseJsonObjectBody, readDataContract, syncFileContract, triggerSyncContract, getSyncStatusContract, configReadErrorContract, configWriteErrorContract, createGrantContract, listGrantsContract, oauthTokenContract, revokeGrantContract, validateServerConfigContract, verifyGrantContract, decodeBinaryEnvelope, isBinaryEnvelope, parseMetadataHeader, stringifyMetadataHeader, } from "../contracts/index.js";
+import { GrantRequiredError, InvalidCascadeError, LineageCascadeUnavailableError, LineageGatewayError, LineageUnavailableError, ProtocolError, ServerNotConfiguredError, } from "../errors/catalog.js";
+import { deleteDataScopeContract, ingestDataContract, ingestBinaryDataContract, listAccessLogsContract, listDataScopesContract, listDataVersionsContract, parseDataScopeContract, parseJsonObjectBody, readDataContract, syncFileContract, triggerSyncContract, getSyncStatusContract, configReadErrorContract, configWriteErrorContract, createGrantContract, listGrantsContract, oauthTokenContract, revokeGrantContract, validateServerConfigContract, verifyGrantContract, decodeBinaryEnvelope, isBinaryEnvelope, parseMetadataHeader, stringifyMetadataHeader, IngestPersistedError, } from "../contracts/index.js";
+import { extractLineageField, prepareLineage, } from "../lineage/lineage.js";
+import { computeDataPointId } from "../sync/data-point-id.js";
+import { binaryFilename, binaryMimeType, isJsonContentType, } from "../contracts/binary.js";
 import { buildChallenge, parsePaymentHeader, verifyPayment, } from "../payment/index.js";
 function jsonResponse(body, init) {
     const headers = new Headers(init?.headers);
@@ -249,30 +252,6 @@ function collectedAt(now) {
         .toISOString()
         .replace(/\.\d{3}Z$/, "Z");
 }
-/** True when the request body should be treated as a JSON object (the legacy
- * path). Missing/blank Content-Type is treated as JSON for backward compat. */
-function isJsonContentType(request) {
-    const ct = request.headers.get("content-type");
-    if (!ct)
-        return true;
-    return ct.toLowerCase().includes("application/json");
-}
-function binaryMimeType(request) {
-    const ct = request.headers.get("content-type");
-    if (!ct)
-        return "application/octet-stream";
-    // Strip any "; charset=..." / boundary parameters.
-    return ct.split(";")[0].trim() || "application/octet-stream";
-}
-/** Extract a filename from X-Filename or a Content-Disposition header. */
-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;
-}
 function notifyNewData(syncManager) {
     if (!syncManager)
         return;
@@ -306,6 +285,73 @@ export function reportPersonalServerReadFulfillment(deps, event) {
         warnReadFulfillmentReporterFailed(deps, event, err);
     }
 }
+/**
+ * Validate a write's caller-supplied `lineage` (JSON body top level, or the
+ * binary metadata object) into the `$lineage` record to stamp. `undefined`
+ * (or null) means a root record. Throws ProtocolErrors; the write handler
+ * lets them propagate before anything is stored.
+ */
+async function prepareWriteLineage(deps, scope, field) {
+    if (field === undefined || field === null)
+        return undefined;
+    return prepareLineage({
+        scope,
+        field,
+        serverOwner: deps.serverOwner,
+        storage: deps.storage,
+        gateway: deps.lineageGateway,
+        now: deps.now ?? (() => new Date()),
+    });
+}
+/**
+ * The lineage view a read auth result entitles the caller to. The auth port
+ * answers an owner read with no result or with the "owner" / "policy-bypass"
+ * sentinels (see api-auth): those get the full view. A builder read carries
+ * the grant the read policy resolved, and that grant names the view. A
+ * builder result with no resolved grant (or an "unknown" one) proves
+ * nothing and is refused: a missing grantId must never widen to the full
+ * view.
+ */
+function resolveLineageGrantView(authResult) {
+    if (authResult === undefined ||
+        authResult.grantId === "owner" ||
+        authResult.grantId === "policy-bypass") {
+        return { grantId: undefined };
+    }
+    const grantId = authResult.grantId;
+    if (typeof grantId !== "string" || grantId === "" || grantId === "unknown") {
+        throw new GrantRequiredError({
+            reason: "a lineage read by a builder needs a resolved grant",
+        });
+    }
+    return { grantId };
+}
+/**
+ * Delete one scope the way DELETE /v1/data/:scope always has: propagate to
+ * the authoritative stores first, best-effort (on DPv2 the remote step is a
+ * logged no-op until the tombstone-based delete lands), then drop the local
+ * copy.
+ */
+async function deleteOneScope(deps, scope) {
+    if (deps.syncManager?.deleteScopeRemote) {
+        try {
+            await deps.syncManager.deleteScopeRemote(scope);
+        }
+        catch (err) {
+            deps.logger?.info?.({ scope, error: err.message }, "Remote scope deletion failed; proceeding with local delete");
+        }
+    }
+    const result = await deleteDataScopeContract({
+        storage: deps.storage,
+        scopeParam: scope,
+    });
+    if (!result.ok) {
+        // The scope was validated by the caller; a contract error here is a bug.
+        throw new ProtocolError(result.status, result.body.error, result.body.message);
+    }
+    deps.logger?.info?.({ scope, deletedCount: result.deletedCount }, "Scope deleted");
+    return result.deletedCount;
+}
 export async function handlePersonalServerDataRequest(request, deps, options = {}) {
     return withApiErrors(async () => {
         const url = new URL(request.url);
@@ -337,6 +383,77 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
                 return contractErrorResponse(result);
             return jsonResponse(result.response);
         }
+        if ((parts.length === 2 || parts.length === 3) && parts[1] === "lineage") {
+            if (request.method !== "GET")
+                return methodNotAllowed();
+            const scopeResult = parseDataScopeContract(decodePathPart(parts[0]));
+            if (!scopeResult.ok)
+                return contractErrorResponse(scopeResult);
+            // The version is a PATH segment (/v1/data/:scope/lineage/:version), so
+            // it is inside the signed request uri: a builder's signature for one
+            // version cannot be replayed to read another. The grant view is the
+            // signed grantId claim the read auth already honours. Query
+            // parameters would be unsigned inputs to the view and are refused.
+            if (url.searchParams.has("version")) {
+                return errorResponse(400, "INVALID_VERSION", "version is a path segment (/v1/data/:scope/lineage/:version), not a query parameter");
+            }
+            if (url.search.length > 0) {
+                return errorResponse(400, "INVALID_QUERY", "lineage reads take no query parameters; the version is a path segment and the grant view is the signed grantId claim");
+            }
+            const version = parts.length === 3 ? decodePathPart(parts[2]) : undefined;
+            if (version !== undefined && !/^[1-9]\d*$/.test(version)) {
+                return errorResponse(400, "INVALID_VERSION", "version must be a positive decimal integer");
+            }
+            // Same gate as a read of the scope: the owner, or a builder whose grant
+            // covers it. The gateway then attests the view that grant sees, so a
+            // builder only learns the scopes of nodes its grant covers.
+            const authResult = await deps.auth.authorizeBuilderRead({
+                request,
+                scope: scopeResult.scope,
+                grantId: selectedGrantId(request, url),
+            });
+            if (!deps.serverOwner) {
+                throw new ServerNotConfiguredError({
+                    reason: "serverOwner is required to resolve the data point id",
+                });
+            }
+            if (!deps.lineageGateway)
+                throw new LineageUnavailableError();
+            const { grantId } = resolveLineageGrantView(authResult);
+            let result;
+            try {
+                result = await deps.lineageGateway.getLineage({
+                    dataPointId: computeDataPointId(deps.serverOwner, scopeResult.scope),
+                    version,
+                    grantId,
+                });
+            }
+            catch (err) {
+                // Transport failures (DNS, refused, timeout) are gateway errors to
+                // the caller, not internal ones: same 502 as a gateway error body.
+                if (err instanceof ProtocolError)
+                    throw err;
+                throw new LineageGatewayError({
+                    status: 0,
+                    body: { error: err instanceof Error ? err.message : String(err) },
+                });
+            }
+            if (!result.ok) {
+                if (result.status === 404) {
+                    return errorResponse(404, "NOT_FOUND", version
+                        ? `Scope "${scopeResult.scope}" has no registered version ${version}`
+                        : `Scope "${scopeResult.scope}" is not registered at the gateway`);
+                }
+                if (result.status === 403) {
+                    throw new ProtocolError(403, "LINEAGE_FORBIDDEN", "The gateway refused the lineage view for this grant", { gateway: result.body });
+                }
+                throw new LineageGatewayError({
+                    status: result.status,
+                    body: result.body,
+                });
+            }
+            return jsonResponse({ data: result.data, proof: result.proof });
+        }
         if (parts.length !== 1)
             return notFound();
         const scopeParam = decodePathPart(parts[0]);
@@ -527,85 +644,179 @@ export async function handlePersonalServerDataRequest(request, deps, options = {
             return response;
         }
         if (request.method === "POST") {
-            await deps.auth.authorizeOwner(request);
-            const scopeResult = parseDataScopeContract(scopeParam);
-            if (!scopeResult.ok)
-                return contractErrorResponse(scopeResult);
-            const collectedAtValue = collectedAt(deps.now ?? (() => new Date()));
-            const status = deps.syncManager ? "syncing" : "stored";
-            // Binary / unstructured data (e.g. a PDF): the body is raw bytes. DPv2
-            // data points are scope-addressed and carry no schemaId, so unstructured
-            // data needs no schema at all — we ingest it schemaless. (Structured JSON
-            // below still resolves a schema for validation/metadata.)
-            if (!isJsonContentType(request)) {
-                const bytes = new Uint8Array(await request.arrayBuffer());
-                const result = await ingestBinaryDataContract({
+            // Delegated writes: an auth port that supports write sessions handles
+            // both paths in authorizeWrite (builder session token -> write policy +
+            // attribution; anything else -> owner path). Ports without it keep
+            // today's owner-only gate.
+            let writeAuth;
+            if (deps.auth.authorizeWrite) {
+                writeAuth =
+                    (await deps.auth.authorizeWrite({ request, scope: scopeParam })) ??
+                        undefined;
+            }
+            else {
+                await deps.auth.authorizeOwner(request);
+            }
+            // A write that fails before commit hands the proof back (replay guard)
+            // so the builder's retry with the same still-valid proof is accepted;
+            // after commit the proof stays consumed (a retry would be a duplicate).
+            let committed = false;
+            const failWrite = async (response) => {
+                await writeAuth?.releaseProof?.();
+                return response;
+            };
+            try {
+                const scopeResult = parseDataScopeContract(scopeParam);
+                if (!scopeResult.ok)
+                    return failWrite(contractErrorResponse(scopeResult));
+                const collectedAtValue = collectedAt(deps.now ?? (() => new Date()));
+                const status = deps.syncManager ? "syncing" : "stored";
+                // Builder writes land in the same access log as builder reads, so the
+                // owner sees who wrote what under which grant.
+                // Best-effort: it runs AFTER the record is committed, so a log failure
+                // must not turn a successful write into a 500 (the builder would retry
+                // and store a duplicate). The ingest log line above still names the
+                // builder; the failure itself is logged for the owner.
+                const logBuilderWrite = async () => {
+                    if (!writeAuth)
+                        return;
+                    try {
+                        await deps.accessLogWriter.write({
+                            logId: deps.createLogId?.() ?? crypto.randomUUID(),
+                            grantId: writeAuth.grantId,
+                            builder: writeAuth.builder,
+                            action: "write",
+                            scope: scopeResult.scope,
+                            timestamp: (deps.now ?? (() => new Date()))().toISOString(),
+                            ipAddress: request.headers.get("x-forwarded-for") ??
+                                request.headers.get("x-real-ip") ??
+                                "unknown",
+                            userAgent: request.headers.get("user-agent") ?? "unknown",
+                        });
+                    }
+                    catch (err) {
+                        deps.logger?.warn?.({
+                            scope: scopeResult.scope,
+                            builder: writeAuth.builder,
+                            grantId: writeAuth.grantId,
+                            error: err instanceof Error ? err.message : String(err),
+                        }, "Builder write access-log entry failed; record already stored");
+                    }
+                };
+                // Binary / unstructured data (e.g. a PDF): the body is raw bytes. DPv2
+                // data points are scope-addressed and carry no schemaId, so unstructured
+                // data needs no schema at all — we ingest it schemaless. (Structured JSON
+                // below still resolves a schema for validation/metadata.)
+                if (!isJsonContentType(request)) {
+                    const bytes = new Uint8Array(await request.arrayBuffer());
+                    const metadata = parseMetadataHeader(request.headers.get("x-vana-metadata"));
+                    // A binary derivative names its sources inside the metadata
+                    // object; the validated mirror lands at the top of the record.
+                    const lineage = await prepareWriteLineage(deps, scopeResult.scope, extractLineageField(metadata));
+                    const result = await ingestBinaryDataContract({
+                        storage: deps.storage,
+                        scopeParam: scopeResult.scope,
+                        bytes,
+                        mimeType: binaryMimeType(request),
+                        filename: binaryFilename(request),
+                        metadata,
+                        collectedAt: collectedAtValue,
+                        status,
+                        attribution: writeAuth?.attribution,
+                        lineage,
+                    });
+                    if (!result.ok)
+                        return failWrite(contractErrorResponse(result));
+                    committed = true;
+                    deps.logger?.info?.({
+                        scope: scopeResult.scope,
+                        collectedAt: collectedAtValue,
+                        path: result.writeResult.relativePath,
+                        mimeType: binaryMimeType(request),
+                        sizeBytes: bytes.length,
+                        ...(writeAuth ? { builder: writeAuth.builder } : {}),
+                    }, "Binary data file ingested");
+                    await logBuilderWrite();
+                    notifyNewData(deps.syncManager);
+                    return jsonResponse(result.response, { status: 201 });
+                }
+                const parsed = await parseJsonObjectBody(request, "Request body must be valid JSON");
+                if (!parsed.ok)
+                    return failWrite(contractResponse(parsed.result));
+                // Derivative writes: validate the caller's `lineage` before anything
+                // is stored (a failure here throws, releasing the builder's proof).
+                const lineage = await prepareWriteLineage(deps, scopeResult.scope, extractLineageField(parsed.body));
+                // DPv2 is scope-addressed and the gateway records no schemas, so JSON
+                // ingest is schemaless too — no lookup, no schemaId/$schema stamped.
+                const result = await ingestDataContract({
                     storage: deps.storage,
                     scopeParam: scopeResult.scope,
-                    bytes,
-                    mimeType: binaryMimeType(request),
-                    filename: binaryFilename(request),
-                    metadata: parseMetadataHeader(request.headers.get("x-vana-metadata")),
+                    body: parsed.body,
                     collectedAt: collectedAtValue,
                     status,
+                    attribution: writeAuth?.attribution,
+                    lineage,
                 });
                 if (!result.ok)
-                    return contractErrorResponse(result);
+                    return failWrite(contractErrorResponse(result));
+                committed = true;
                 deps.logger?.info?.({
                     scope: scopeResult.scope,
                     collectedAt: collectedAtValue,
                     path: result.writeResult.relativePath,
-                    mimeType: binaryMimeType(request),
-                    sizeBytes: bytes.length,
-                }, "Binary data file ingested");
+                    ...(writeAuth ? { builder: writeAuth.builder } : {}),
+                }, "Data file ingested");
+                await logBuilderWrite();
                 notifyNewData(deps.syncManager);
                 return jsonResponse(result.response, { status: 201 });
             }
-            const parsed = await parseJsonObjectBody(request, "Request body must be valid JSON");
-            if (!parsed.ok)
-                return contractResponse(parsed.result);
-            // DPv2 is scope-addressed and the gateway records no schemas, so JSON
-            // ingest is schemaless too — no lookup, no schemaId/$schema stamped.
-            const result = await ingestDataContract({
-                storage: deps.storage,
-                scopeParam: scopeResult.scope,
-                body: parsed.body,
-                collectedAt: collectedAtValue,
-                status,
-            });
-            if (!result.ok)
-                return contractErrorResponse(result);
-            deps.logger?.info?.({
-                scope: scopeResult.scope,
-                collectedAt: collectedAtValue,
-                path: result.writeResult.relativePath,
-            }, "Data file ingested");
-            notifyNewData(deps.syncManager);
-            return jsonResponse(result.response, { status: 201 });
+            catch (err) {
+                // An envelope that reached storage before indexing failed is
+                // persisted (a re-index surfaces it): keep the proof consumed so a
+                // retry cannot store it twice; the builder needs a fresh proof.
+                if (err instanceof IngestPersistedError) {
+                    deps.logger?.error?.({
+                        scope: scopeParam,
+                        path: err.relativePath,
+                        error: err.cause instanceof Error
+                            ? err.cause.message
+                            : String(err.cause),
+                    }, "Envelope written but indexing failed; record persisted unindexed");
+                }
+                else if (!committed) {
+                    await writeAuth?.releaseProof?.();
+                }
+                throw err;
+            }
         }
         if (request.method === "DELETE") {
             await deps.auth.authorizeOwner(request);
-            // Propagate the deletion to the authoritative stores (R2 blobs + gateway records) BEFORE the
-            // local delete — it reads the local index to find what to remove. Best-effort: a remote
-            // failure must not block the owner's local delete (and sync would otherwise resurrect it; the
-            // download-worker reconciliation is the backstop). Parse the scope first so an invalid scope
-            // still 400s without a wasted remote call.
+            const cascade = url.searchParams.get("cascade");
+            if (cascade !== null && cascade !== "lineage") {
+                throw new InvalidCascadeError({ cascade });
+            }
+            // Parse the scope first so an invalid scope still 400s without a
+            // wasted remote call.
             const parsed = parseDataScopeContract(scopeParam);
-            if (parsed.ok && deps.syncManager?.deleteScopeRemote) {
-                try {
-                    await deps.syncManager.deleteScopeRemote(parsed.scope);
-                }
-                catch (err) {
-                    deps.logger?.info?.({ scope: scopeParam, error: err.message }, "Remote scope deletion failed; proceeding with local delete");
-                }
+            if (!parsed.ok)
+                return contractErrorResponse(parsed);
+            if (cascade === "lineage") {
+                // Specified (docs/derivative-data-api.md, "Delete") but not
+                // implemented here: the cascade must tombstone every derivative at
+                // the gateway, and DPv2 deletion is separate work (the tombstone
+                // based delete branch). Until that lands the only honest answer is
+                // 501; a local-only cascade would report derivatives deleted while
+                // their gateway records and ciphertext remain and sync could bring
+                // them back.
+                throw new LineageCascadeUnavailableError({ scope: parsed.scope });
             }
-            const result = await deleteDataScopeContract({
-                storage: deps.storage,
-                scopeParam,
-            });
-            if (!result.ok)
-                return contractErrorResponse(result);
-            deps.logger?.info?.({ scope: scopeParam, deletedCount: result.deletedCount }, "Scope deleted");
+            // Single node (the default): propagate the deletion to the
+            // authoritative stores (R2 blobs + gateway records) BEFORE the local
+            // delete, which reads the local index to find what to remove.
+            // Best-effort: a remote failure must not block the owner's local delete
+            // (sync would otherwise resurrect it; the download-worker
+            // reconciliation is the backstop).
+            await deleteOneScope(deps, parsed.scope);
             return new Response(null, { status: 204 });
         }
         return methodNotAllowed();