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

package/dist/write/attribution.js

@@ -0,0 +1,325 @@
+/**
+ * Builder attribution for delegated writes.
+ *
+ * The write-session token authorizes a write; it does not PROVE who authored
+ * the payload (a bearer token is not a signature). For cryptographic
+ * attribution the builder also signs the payload: a Web3Signed proof over the
+ * exact write request (aud / method / uri / bodyHash / iat / exp), carried in
+ * the `X-Vana-Write-Signature` header and signed by the builder key proven at
+ * handshake. The PS verifies the proof recovers to the session's builder and
+ * that its bodyHash commits to the received bytes, then stores the proof and
+ * the builder identity WITH the record — inside the envelope's `data` under
+ * the reserved `$writtenBy` key (same in-`data` marker idiom as `$binary`),
+ * so attribution travels through the unchanged encrypt / upload / register
+ * path and back out on read. The on-chain shape is untouched.
+ *
+ * The proof binds the write to its context, not just its bytes: the signed
+ * claims carry the request path (whose last segment is the scope), the
+ * method, the audience (this server's origin) and the session's grantId,
+ * which the PS requires to match the session at ingest. A stored `$writtenBy`
+ * therefore cannot be lifted onto another scope's record or relabelled with a
+ * different grant and still verify.
+ *
+ * What the builder signs is the STORED representation, not the wire body:
+ * the compact JSON of the envelope `data` record the PS will write (minus
+ * `$writtenBy`). A third party holding the envelope can therefore verify
+ * authorship from the envelope ALONE (verifyStoredWriterAttribution): recover
+ * the signer over the stored proof's base64url payload (EIP-191), check the
+ * signed claims against the envelope's scope and stored grantId, and hash
+ * JSON.stringify(data minus the server-stamped keys `$writtenBy` and
+ * `$lineage`) against the signed bodyHash.
+ *   - JSON writes: the body IS the stored record, so the builder signs the
+ *     body bytes, which must be compact JSON (what JSON.stringify emits: no
+ *     insignificant whitespace, keys in the order given). JSON.parse /
+ *     JSON.stringify round-trips that byte-for-byte; a body that does not
+ *     round-trip is rejected at write time (WRITE_BODY_NOT_CANONICAL) instead
+ *     of being stored with an attribution nobody can check.
+ *   - Binary writes: the stored record is the `$binary` envelope data (media
+ *     type, filename, caller metadata, size, content hash, base64 content),
+ *     so the builder signs its compact JSON (binaryWriteSignedBytes). That
+ *     binds the caller-controlled representation headers (Content-Type,
+ *     X-Filename / Content-Disposition, X-Vana-Metadata) to the signature and
+ *     makes a JSON-vs-binary switch of the same bytes fail verification.
+ */
+import { computeBodyHash, parseWeb3SignedHeader, verifyWeb3Signed, } from "@opendatalabs/vana-sdk/browser";
+import { recoverMessageAddress } from "viem";
+import { ProtocolError } from "../errors/catalog.js";
+import { hashConnectionToken as sha256HexOf } from "../mcp/connection-api.js";
+import { binaryFilename, binaryMimeType, buildBinaryEnvelopeData, isJsonContentType, normalizeBinaryMimeType, parseMetadataHeader, sha256Hex, } from "../contracts/binary.js";
+import { LINEAGE_KEY, StoredLineageMalformedError, extractLineageField, readStoredLineage, } from "../lineage/lineage.js";
+import { isBinaryEnvelope } from "../contracts/binary.js";
+/** Header carrying the builder's signed-payload proof on a session write. */
+export const WRITE_SIGNATURE_HEADER = "x-vana-write-signature";
+/**
+ * Reserved key inside the envelope's `data` record for builder attribution.
+ * Mirrors the `$binary` marker convention (contracts/binary.ts).
+ */
+export const WRITER_ATTRIBUTION_KEY = "$writtenBy";
+function resolveOrigin(origin) {
+    return typeof origin === "function" ? origin() : origin;
+}
+/**
+ * The bytes a builder signs (as the Web3Signed body) for a BINARY session
+ * write: the compact JSON of the `$binary` record the PS stores for these
+ * headers and bytes. Mirrors ingest exactly (same media-type normalization,
+ * metadata parsing and envelope builder), so the signature covers the stored
+ * representation and verifyStoredWriterAttribution can re-derive it.
+ */
+export async function binaryWriteSignedBytes(input) {
+    const data = buildBinaryEnvelopeData({
+        bytes: input.bytes,
+        mimeType: normalizeBinaryMimeType(input.contentType),
+        filename: input.filename,
+        contentHash: await sha256Hex(input.bytes),
+        metadata: parseMetadataHeader(input.metadataHeader ?? null),
+    });
+    return new TextEncoder().encode(JSON.stringify(data));
+}
+/**
+ * The bytes the proof must commit to for this request: the body itself for
+ * a JSON write, the stored `$binary` representation for anything else.
+ */
+async function signedBytesFor(request, bodyBytes) {
+    if (isJsonContentType(request))
+        return bodyBytes;
+    return binaryWriteSignedBytes({
+        bytes: bodyBytes,
+        contentType: binaryMimeType(request),
+        filename: binaryFilename(request),
+        metadataHeader: request.headers.get("x-vana-metadata") ?? undefined,
+    });
+}
+/**
+ * Verify the `X-Vana-Write-Signature` proof on a session write and produce
+ * the attribution record to store with the data. Throws ProtocolError(401)
+ * when the proof is missing, malformed, expired, fails EIP-191 recovery /
+ * bodyHash binding (the hash covers the stored representation, see
+ * signedBytesFor), recovers to a different key than the session builder, or
+ * does not carry the session's grantId as a signed claim.
+ */
+export async function verifyWriterAttribution(input) {
+    const headerValue = input.request.headers.get(WRITE_SIGNATURE_HEADER) ?? undefined;
+    if (!headerValue) {
+        throw new ProtocolError(401, "WRITE_ATTRIBUTION_REQUIRED", `Session writes must carry a builder-signed payload proof in ${WRITE_SIGNATURE_HEADER}`);
+    }
+    const url = new URL(input.request.url);
+    const bodyBytes = new Uint8Array(await input.request.clone().arrayBuffer());
+    let verified;
+    try {
+        verified = await verifyWeb3Signed({
+            headerValue,
+            expectedOrigin: resolveOrigin(input.serverOrigin),
+            expectedMethod: input.request.method,
+            expectedPath: url.pathname,
+            bodyBytes: await signedBytesFor(input.request, bodyBytes),
+        });
+    }
+    catch (err) {
+        throw new ProtocolError(401, "WRITE_ATTRIBUTION_INVALID", err instanceof Error ? err.message : String(err));
+    }
+    if (verified.signer.toLowerCase() !== input.builderAddress.toLowerCase()) {
+        throw new ProtocolError(401, "WRITE_ATTRIBUTION_SIGNER_MISMATCH", "Payload proof is not signed by the session builder", { expected: input.builderAddress, actual: verified.signer });
+    }
+    // The grant is a signed claim, so the stored attribution's grantId is
+    // covered by the builder's signature rather than being a bare label.
+    if (verified.payload.grantId !== input.grantId) {
+        throw new ProtocolError(401, "WRITE_ATTRIBUTION_GRANT_MISMATCH", "Payload proof must carry the write session's grantId as a signed claim", { expected: input.grantId, actual: verified.payload.grantId ?? null });
+    }
+    if (isJsonContentType(input.request)) {
+        assertCanonicalJsonBody(bodyBytes);
+    }
+    // Replay guard, last: only a proof that passed every check is consumed,
+    // so a rejected request never burns a proof.
+    let releaseProof;
+    if (input.replayStore) {
+        const store = input.replayStore;
+        const proofId = await sha256HexOf(headerValue);
+        const replayed = await store.consume(proofId, verified.payload.exp * 1000);
+        if (replayed) {
+            throw new ProtocolError(401, "WRITE_ATTRIBUTION_REPLAY", "Payload proof already used; sign a fresh proof for each write");
+        }
+        releaseProof = async () => {
+            await store.release?.(proofId);
+        };
+    }
+    // Store the compact `{payload}.{signature}` form (scheme prefix stripped)
+    // so verifiers don't need to know the header framing.
+    const { payloadBase64, signature } = parseWeb3SignedHeader(headerValue);
+    return {
+        builder: input.builderAddress,
+        grantId: input.grantId,
+        signature: `${payloadBase64}.${signature}`,
+        bodyHash: verified.payload.bodyHash,
+        writtenAt: (input.now?.() ?? new Date()).toISOString(),
+        ...(releaseProof ? { releaseProof } : {}),
+    };
+}
+/**
+ * Stamp attribution into an envelope `data` record. The reserved key must not
+ * appear in the caller's payload — a builder must not be able to forge (or
+ * shadow) its own attribution.
+ */
+export function stampWriterAttribution(data, attribution) {
+    return { ...data, [WRITER_ATTRIBUTION_KEY]: attribution };
+}
+export function hasReservedWriterKey(data) {
+    return Object.prototype.hasOwnProperty.call(data, WRITER_ATTRIBUTION_KEY);
+}
+/**
+ * A JSON session write must be the compact serialization of its own parsed
+ * value, so the record stored after JSON.parse re-serializes to the signed
+ * bytes. Bodies that do not parse are left to the ingest path, which reports
+ * the parse error itself.
+ */
+function assertCanonicalJsonBody(bodyBytes) {
+    const text = new TextDecoder().decode(bodyBytes);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    if (JSON.stringify(parsed) !== text) {
+        throw new ProtocolError(400, "WRITE_BODY_NOT_CANONICAL", "Session writes must send compact JSON (the JSON.stringify form) so the stored record re-serializes to the signed bytes and the attribution bodyHash stays verifiable");
+    }
+}
+/** Proof scheme prefix the compact stored signature was stripped of. */
+const WEB3_SIGNED_SCHEME = "Web3Signed";
+export class WriterAttributionVerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "WriterAttributionVerificationError";
+    }
+}
+function isWriterAttribution(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.builder === "string" &&
+        v.builder.startsWith("0x") &&
+        typeof v.grantId === "string" &&
+        typeof v.signature === "string" &&
+        typeof v.bodyHash === "string" &&
+        typeof v.writtenAt === "string");
+}
+/** Last path segment of the signed request uri, i.e. the scope written to. */
+function signedScopeOf(uri) {
+    const path = uri.split("?")[0] ?? "";
+    const segment = path.slice(path.lastIndexOf("/") + 1);
+    if (!segment)
+        return null;
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify builder attribution from a stored envelope alone (no request, no
+ * server state, no expiry check: the proof is evidence of who wrote the
+ * record at the time, not a live credential). Checks, in order: the envelope
+ * carries an attribution; the stored representation (compact JSON of the
+ * data minus the server-stamped `$writtenBy` and `$lineage` keys, for JSON
+ * and `$binary` records alike) re-hashes
+ * to the signed bodyHash; the proof parses and recovers to the attributed
+ * builder; and the signed claims bind the proof to THIS record: a POST whose
+ * path names the envelope's scope, the stored grantId, and (when given) the
+ * server origin. Throws WriterAttributionVerificationError with the reason.
+ */
+export async function verifyStoredWriterAttribution(envelope, options = {}) {
+    const data = envelope.data;
+    const attribution = data[WRITER_ATTRIBUTION_KEY];
+    if (!isWriterAttribution(attribution)) {
+        throw new WriterAttributionVerificationError("ATTRIBUTION_MISSING", `Record carries no ${WRITER_ATTRIBUTION_KEY} attribution`);
+    }
+    // Every server-stamped reserved key is stripped, not just the attribution:
+    // `$lineage` is the server's validated mirror of the caller's `lineage`
+    // field (the field itself stays inside the signed bytes), so a derivative
+    // record re-hashes to the same signed bodyHash as a root record.
+    const { [WRITER_ATTRIBUTION_KEY]: _attribution, [LINEAGE_KEY]: storedLineage, ...payloadData } = data;
+    const bodyHash = computeBodyHash(new TextEncoder().encode(JSON.stringify(payloadData)));
+    if (bodyHash !== attribution.bodyHash) {
+        throw new WriterAttributionVerificationError("BODY_HASH_MISMATCH", "Stored record does not hash to the attribution bodyHash");
+    }
+    let proof;
+    let signer;
+    try {
+        proof = parseWeb3SignedHeader(`${WEB3_SIGNED_SCHEME} ${attribution.signature}`);
+        signer = await recoverMessageAddress({
+            message: proof.payloadBase64,
+            signature: proof.signature,
+        });
+    }
+    catch (err) {
+        throw new WriterAttributionVerificationError("PROOF_INVALID", err instanceof Error ? err.message : String(err));
+    }
+    if (proof.payload.bodyHash !== bodyHash) {
+        throw new WriterAttributionVerificationError("BODY_HASH_MISMATCH", "Stored proof does not commit to the attribution bodyHash");
+    }
+    if (signer.toLowerCase() !== attribution.builder.toLowerCase()) {
+        throw new WriterAttributionVerificationError("SIGNER_MISMATCH", "Stored proof is not signed by the attributed builder");
+    }
+    // Context binding: the signed claims must describe a write of THIS record.
+    if (proof.payload.method !== "POST" ||
+        signedScopeOf(proof.payload.uri) !== envelope.scope) {
+        throw new WriterAttributionVerificationError("SCOPE_MISMATCH", `Stored proof is not a write to scope ${envelope.scope}`);
+    }
+    if (proof.payload.grantId !== attribution.grantId) {
+        throw new WriterAttributionVerificationError("GRANT_MISMATCH", "Stored grantId is not the grant the builder signed");
+    }
+    if (options.expectedOrigin !== undefined &&
+        proof.payload.aud !== options.expectedOrigin) {
+        throw new WriterAttributionVerificationError("AUDIENCE_MISMATCH", "Stored proof was not addressed to this server");
+    }
+    // The stripped mirror is not unauthenticated for that: it must restate
+    // the builder-signed `lineage` field (body top level, or the binary
+    // record's metadata object) in both directions, so a `$lineage` edited
+    // after the write, or one removed to hide a derivative's sources, is
+    // caught even though it is outside the hashed bytes. A signed list
+    // (empty included: an explicit root statement) must have its mirror; an
+    // absent signed field must have none.
+    const signedField = extractLineageField(isBinaryEnvelope({ data: payloadData })
+        ? payloadData.metadata
+        : payloadData);
+    // Absent or null means "no statement". Anything else that is not a list
+    // of strings is a malformed signed field: an independently constructed
+    // record must not pass verification just because its lineage claim is
+    // unreadable, so it is a mismatch, never "absent".
+    const signedAbsent = signedField === undefined || signedField === null;
+    const signedWellFormed = Array.isArray(signedField) &&
+        signedField.every((id) => typeof id === "string");
+    const signed = signedAbsent || !signedWellFormed
+        ? null
+        : signedField.map((id) => id.toLowerCase());
+    let mirror;
+    try {
+        mirror = storedLineage === undefined ? null : readStoredLineage(data);
+    }
+    catch (error) {
+        if (error instanceof StoredLineageMalformedError) {
+            throw new WriterAttributionVerificationError("LINEAGE_MISMATCH", `stored $lineage mirror is malformed: ${error.message}`);
+        }
+        throw error;
+    }
+    const consistent = !signedAbsent && !signedWellFormed
+        ? false
+        : signed === null
+            ? storedLineage === undefined
+            : mirror !== null &&
+                signed.length === mirror.sources.length &&
+                signed.every((id, i) => id === mirror.sources[i]);
+    if (!consistent) {
+        throw new WriterAttributionVerificationError("LINEAGE_MISMATCH", "Stored $lineage does not restate the builder-signed lineage field");
+    }
+    return {
+        builder: attribution.builder,
+        grantId: attribution.grantId,
+        bodyHash,
+        payload: proof.payload,
+    };
+}
+//# sourceMappingURL=attribution.js.map

package/dist/write/attribution.js.map

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

package/dist/write/index.d.ts

@@ -0,0 +1,3 @@
+export { createInMemoryWriteProofReplayStore, createInMemoryWriteSessionStore, createWriteSession, hashWriteSessionToken, type CreateWriteSessionInput, type CreateWriteSessionOptions, type CreateWriteSessionResult, type WriteProofReplayStore, type WriteSessionRecord, type WriteSessionStore, } from "./session.js";
+export { WRITE_SIGNATURE_HEADER, WRITER_ATTRIBUTION_KEY, binaryWriteSignedBytes, hasReservedWriterKey, stampWriterAttribution, verifyStoredWriterAttribution, verifyWriterAttribution, WriterAttributionVerificationError, type BinaryWriteSignedBytesInput, type StoredWriterAttributionVerification, type VerifiedWriterAttribution, type VerifyStoredWriterAttributionOptions, type VerifyWriterAttributionInput, type WriterAttribution, } from "./attribution.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/write/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,+BAA+B,EAC/B,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,kCAAkC,EAClC,KAAK,2BAA2B,EAChC,KAAK,mCAAmC,EACxC,KAAK,yBAAyB,EAC9B,KAAK,oCAAoC,EACzC,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/write/index.js

@@ -0,0 +1,3 @@
+export { createInMemoryWriteProofReplayStore, createInMemoryWriteSessionStore, createWriteSession, hashWriteSessionToken, } from "./session.js";
+export { WRITE_SIGNATURE_HEADER, WRITER_ATTRIBUTION_KEY, binaryWriteSignedBytes, hasReservedWriterKey, stampWriterAttribution, verifyStoredWriterAttribution, verifyWriterAttribution, WriterAttributionVerificationError, } from "./attribution.js";
+//# sourceMappingURL=index.js.map

package/dist/write/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/write/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mCAAmC,EACnC,+BAA+B,EAC/B,kBAAkB,EAClB,qBAAqB,GAOtB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,kCAAkC,GAOnC,MAAM,kBAAkB,CAAC"}

package/dist/write/session.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Write API session (server-signed delegated writes, v1).
+ *
+ * A registered builder that holds its OWN key and a WRITE-grant proves control
+ * of that key ONCE — a Web3Signed handshake to `POST /v1/write/session` — and
+ * the PS mints a short-lived bearer token bound to `{ builderAddress, grantId }`
+ * (the grant's `write:`-prefixed scope entries define what it may write).
+ * Writes then present that token on the EXISTING ingest endpoint
+ * (`POST /v1/data/:scope`); each write authorizes as the builder via
+ * `verifyDataWritePolicy` and the PS ingests / encrypts / uploads / registers
+ * through the normal owner path — the PS signs AddData as the owner exactly as
+ * it does today, and the builder never holds the owner key.
+ *
+ * Deliberately the same handshake shape as the self-signing MCP session
+ * (mcp/session.ts): prove key control once, short-lived bearer after. The
+ * session token is authorization only; per-write builder ATTRIBUTION is a
+ * separate signed proof (see ./attribution.ts).
+ */
+import { hashConnectionToken } from "../mcp/connection-api.js";
+import { createInMemoryMcpProofReplayStore, type McpProofReplayStore } from "../mcp/session.js";
+import type { AuthSessionVerifierPort, GrantVerifierPort } from "../ports/index.js";
+export type WriteProofReplayStore = McpProofReplayStore;
+export declare const createInMemoryWriteProofReplayStore: typeof createInMemoryMcpProofReplayStore;
+export declare const hashWriteSessionToken: typeof hashConnectionToken;
+export interface WriteSessionRecord {
+    /** SHA-256 hex of the raw session token. Only the hash is stored. */
+    tokenHash: string;
+    /** The builder's address (recovered from the handshake proof). */
+    builderAddress: `0x${string}`;
+    /** The write-grant id the builder was issued (grantee == builder). */
+    grantId: string;
+    /** The grant's write patterns at handshake time (prefix stripped). */
+    writeScopes: string[];
+    createdAt: string;
+    expiresAtMs: number;
+}
+export interface WriteSessionStore {
+    create(record: WriteSessionRecord): Promise<void>;
+    /** Returns a live (non-expired) session, or null. */
+    getByTokenHash(tokenHash: string): Promise<WriteSessionRecord | null>;
+}
+/**
+ * KNOWN LIMITATION: in-memory only, same trade-off as the MCP session store —
+ * a process restart drops live tokens and the builder must re-handshake.
+ * Acceptable for today's single-instance Personal Server; persist via the
+ * host's state store before multi-instance.
+ */
+export declare function createInMemoryWriteSessionStore(): WriteSessionStore;
+export interface CreateWriteSessionInput {
+    builderAddress: `0x${string}`;
+    grantId: string;
+    /**
+     * Handshake-proof replay guard. When supplied together with a `replayStore`,
+     * a proof id already seen (and still live) is rejected instead of minting a
+     * fresh token. `expiresAtMs` bounds how long the id is remembered (the
+     * proof's own expiry).
+     */
+    proof?: {
+        id: string;
+        expiresAtMs: number;
+    };
+}
+export interface CreateWriteSessionOptions {
+    store: WriteSessionStore;
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    /**
+     * This server's owner address. The grant's grantor MUST equal it — mirrors
+     * `verifyDataWritePolicy`'s ownership binding, applied at handshake so a
+     * wrong-owner grant fails with a clear error instead of minting a token
+     * whose every write would 403.
+     */
+    serverOwner: `0x${string}`;
+    randomToken: () => string;
+    ttlMs?: number;
+    now?: () => number;
+    /** Optional replay guard for the handshake proof (see `input.proof`). */
+    replayStore?: WriteProofReplayStore;
+}
+export interface CreateWriteSessionResult {
+    accessToken: string;
+    expiresInSeconds: number;
+    grantId: string;
+    /** Write patterns (prefix stripped) the session may write into. */
+    writeScopes: string[];
+}
+/**
+ * Validate the handshake identity and mint a write-session token. Same
+ * division of labor as createMcpSession: the handshake does the minimal
+ * checks that give a clear error (builder registered, grant exists + not
+ * revoked + carries write scopes, grantee == builder, grantor == owner);
+ * per-scope / expiry enforcement stays authoritative at write time, where
+ * `verifyDataWritePolicy` runs against the live grant on every POST.
+ */
+export declare function createWriteSession(input: CreateWriteSessionInput, options: CreateWriteSessionOptions): Promise<CreateWriteSessionResult>;
+//# sourceMappingURL=session.d.ts.map

package/dist/write/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/write/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACL,iCAAiC,EACjC,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAc3B,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AACxD,eAAO,MAAM,mCAAmC,0CACb,CAAC;AACpC,eAAO,MAAM,qBAAqB,4BAAsB,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,qDAAqD;IACrD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,IAAI,iBAAiB,CAgBnE;AAID,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,KAAK,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,iBAAiB,CAAC;IACzB,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,aAAa,EAAE,iBAAiB,CAAC;IACjC;;;;;OAKG;IACH,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,yEAAyE;IACzE,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA4FnC"}

package/dist/write/session.js

@@ -0,0 +1,136 @@
+/**
+ * Write API session (server-signed delegated writes, v1).
+ *
+ * A registered builder that holds its OWN key and a WRITE-grant proves control
+ * of that key ONCE — a Web3Signed handshake to `POST /v1/write/session` — and
+ * the PS mints a short-lived bearer token bound to `{ builderAddress, grantId }`
+ * (the grant's `write:`-prefixed scope entries define what it may write).
+ * Writes then present that token on the EXISTING ingest endpoint
+ * (`POST /v1/data/:scope`); each write authorizes as the builder via
+ * `verifyDataWritePolicy` and the PS ingests / encrypts / uploads / registers
+ * through the normal owner path — the PS signs AddData as the owner exactly as
+ * it does today, and the builder never holds the owner key.
+ *
+ * Deliberately the same handshake shape as the self-signing MCP session
+ * (mcp/session.ts): prove key control once, short-lived bearer after. The
+ * session token is authorization only; per-write builder ATTRIBUTION is a
+ * separate signed proof (see ./attribution.ts).
+ */
+import { hashConnectionToken } from "../mcp/connection-api.js";
+import { createInMemoryMcpProofReplayStore, } from "../mcp/session.js";
+import { writeScopePatterns } from "../policy/data-write.js";
+import { GrantOwnerMismatchError, GrantRequiredError, GrantRevokedError, InvalidSignatureError, ProtocolError, ScopeMismatchError, UnregisteredBuilderError, } from "../errors/catalog.js";
+export const createInMemoryWriteProofReplayStore = createInMemoryMcpProofReplayStore;
+export const hashWriteSessionToken = hashConnectionToken;
+/**
+ * KNOWN LIMITATION: in-memory only, same trade-off as the MCP session store —
+ * a process restart drops live tokens and the builder must re-handshake.
+ * Acceptable for today's single-instance Personal Server; persist via the
+ * host's state store before multi-instance.
+ */
+export function createInMemoryWriteSessionStore() {
+    const byHash = new Map();
+    return {
+        async create(record) {
+            byHash.set(record.tokenHash, record);
+        },
+        async getByTokenHash(tokenHash) {
+            const record = byHash.get(tokenHash);
+            if (!record)
+                return null;
+            if (record.expiresAtMs <= Date.now()) {
+                byHash.delete(tokenHash);
+                return null;
+            }
+            return record;
+        },
+    };
+}
+const DEFAULT_SESSION_TTL_MS = 60 * 60 * 1000;
+/**
+ * Validate the handshake identity and mint a write-session token. Same
+ * division of labor as createMcpSession: the handshake does the minimal
+ * checks that give a clear error (builder registered, grant exists + not
+ * revoked + carries write scopes, grantee == builder, grantor == owner);
+ * per-scope / expiry enforcement stays authoritative at write time, where
+ * `verifyDataWritePolicy` runs against the live grant on every POST.
+ */
+export async function createWriteSession(input, options) {
+    const builder = await options.authSessionVerifier.getBuilder(input.builderAddress);
+    if (!builder)
+        throw new UnregisteredBuilderError();
+    const grant = await options.grantVerifier.getGrant(input.grantId);
+    if (!grant) {
+        throw new GrantRequiredError({
+            reason: "Grant not found",
+            grantId: input.grantId,
+        });
+    }
+    if (grant.revokedAt !== null) {
+        throw new GrantRevokedError({ grantId: grant.id });
+    }
+    const patterns = writeScopePatterns(grant.scopes ?? []);
+    if (patterns.length === 0) {
+        throw new ScopeMismatchError({
+            reason: "Grant has no write scopes (write-grant entries use the write: prefix)",
+            grantedScopes: grant.scopes ?? [],
+        });
+    }
+    if (builder.id.toLowerCase() !== grant.granteeId.toLowerCase()) {
+        throw new InvalidSignatureError({
+            reason: "Handshake signer is not the grant builder",
+            expected: grant.granteeId,
+            actual: input.builderAddress,
+        });
+    }
+    // Ownership binding — fail closed on a grantor-less grant: gateway
+    // responses are untrusted runtime data, despite their type.
+    if (!grant.grantorAddress ||
+        grant.grantorAddress.toLowerCase() !== options.serverOwner.toLowerCase()) {
+        throw new GrantOwnerMismatchError({
+            grantId: grant.id,
+            expected: options.serverOwner,
+            actual: grant.grantorAddress ?? null,
+        });
+    }
+    // Prepare the token first (deterministic, can't meaningfully fail) so the
+    // only fallible step after consuming the proof is persistence.
+    const token = options.randomToken();
+    const tokenHash = await hashWriteSessionToken(token);
+    const ttlMs = options.ttlMs ?? DEFAULT_SESSION_TTL_MS;
+    const nowMs = options.now?.() ?? Date.now();
+    // Replay guard: a still-valid handshake proof must mint at most one token.
+    // Same consume/rollback discipline as createMcpSession.
+    const usingReplayGuard = Boolean(input.proof && options.replayStore);
+    if (input.proof && options.replayStore) {
+        const replayed = await options.replayStore.consume(input.proof.id, input.proof.expiresAtMs);
+        if (replayed) {
+            throw new ProtocolError(401, "WRITE_SESSION_PROOF_REPLAY", "Handshake proof already used; sign a fresh proof");
+        }
+    }
+    try {
+        await options.store.create({
+            tokenHash,
+            builderAddress: input.builderAddress,
+            grantId: grant.id,
+            writeScopes: patterns,
+            createdAt: new Date(nowMs).toISOString(),
+            expiresAtMs: nowMs + ttlMs,
+        });
+    }
+    catch (err) {
+        // Persistence failed — release the reservation so a legitimate retry with
+        // the same still-valid proof isn't rejected as a replay.
+        if (usingReplayGuard && input.proof && options.replayStore?.release) {
+            await options.replayStore.release(input.proof.id);
+        }
+        throw err;
+    }
+    return {
+        accessToken: token,
+        expiresInSeconds: Math.floor(ttlMs / 1000),
+        grantId: grant.id,
+        writeScopes: patterns,
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/write/session.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/personal-server-ts-core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Protocol logic for the Vana Personal Server — auth, grants, scopes, storage, keys",
   "license": "MIT",
   "repository": {
@@ -80,6 +80,10 @@
       "types": "./dist/policy/index.d.ts",
       "import": "./dist/policy/index.js"
     },
+    "./lineage": {
+      "types": "./dist/lineage/index.d.ts",
+      "import": "./dist/lineage/index.js"
+    },
     "./ports": {
       "types": "./dist/ports/index.d.ts",
       "import": "./dist/ports/index.js"
@@ -123,6 +127,10 @@
     "./payment": {
       "types": "./dist/payment/index.d.ts",
       "import": "./dist/payment/index.js"
+    },
+    "./write": {
+      "types": "./dist/write/index.d.ts",
+      "import": "./dist/write/index.js"
     }
   },
   "scripts": {