@opendatalabs/personal-server-ts-core 1.4.0 → 1.6.0

package/dist/write/attribution.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 $writtenBy) 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 { type Web3SignedPayload } from "@opendatalabs/vana-sdk/browser";
+import type { WriteProofReplayStore } from "./session.js";
+/** Header carrying the builder's signed-payload proof on a session write. */
+export declare 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 declare const WRITER_ATTRIBUTION_KEY: "$writtenBy";
+export interface WriterAttribution {
+    /** The builder address the proof recovered to. */
+    builder: `0x${string}`;
+    /** The write-grant the record was written under. */
+    grantId: string;
+    /**
+     * The builder's compact Web3Signed proof (`{base64url(payload)}.{sig}`,
+     * scheme prefix stripped). Verifiable offline: recover the EIP-191 signer
+     * over the base64url payload string; the decoded payload's `bodyHash`
+     * commits to the written bytes.
+     */
+    signature: string;
+    /** `bodyHash` claim from the proof (sha-256 of the request body bytes). */
+    bodyHash: string;
+    /** ISO timestamp the PS accepted the write. */
+    writtenAt: string;
+}
+export interface VerifyWriterAttributionInput {
+    request: Request;
+    /** The builder address bound to the write session at handshake. */
+    builderAddress: `0x${string}`;
+    /** The grant the session (and therefore this write) is bound to. */
+    grantId: string;
+    serverOrigin: string | (() => string);
+    now?: () => Date;
+    /**
+     * Replay guard for the per-write proof. When supplied, a proof is consumed
+     * on successful verification (keyed by a digest of the exact header,
+     * remembered until the proof's own expiry) and a second write carrying the
+     * same proof is rejected: holding the session bearer plus one captured
+     * signed request must not allow re-storing it until the proof expires.
+     */
+    replayStore?: WriteProofReplayStore;
+}
+/** verifyWriterAttribution's result: the record to store plus a rollback. */
+export interface VerifiedWriterAttribution extends WriterAttribution {
+    /**
+     * Present when a replay store consumed the proof. Callers whose write then
+     * FAILS before the record is committed should call it so the builder can
+     * retry with the same still-valid proof (a retry after success is a replay).
+     */
+    releaseProof?: () => Promise<void>;
+}
+export interface BinaryWriteSignedBytesInput {
+    /** The raw body bytes the write will send. */
+    bytes: Uint8Array;
+    /** The Content-Type header the write will send (parameters are ignored). */
+    contentType: string;
+    /** The X-Filename header value the write will send, if any. */
+    filename?: string;
+    /** The exact X-Vana-Metadata header value the write will send, if any. */
+    metadataHeader?: string;
+}
+/**
+ * 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 declare function binaryWriteSignedBytes(input: BinaryWriteSignedBytesInput): Promise<Uint8Array>;
+/**
+ * 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 declare function verifyWriterAttribution(input: VerifyWriterAttributionInput): Promise<VerifiedWriterAttribution>;
+/**
+ * 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 declare function stampWriterAttribution(data: Record<string, unknown>, attribution: WriterAttribution): Record<string, unknown>;
+export declare function hasReservedWriterKey(data: Record<string, unknown>): boolean;
+export declare class WriterAttributionVerificationError extends Error {
+    readonly reason: "ATTRIBUTION_MISSING" | "BODY_HASH_MISMATCH" | "PROOF_INVALID" | "SIGNER_MISMATCH" | "SCOPE_MISMATCH" | "GRANT_MISMATCH" | "AUDIENCE_MISMATCH";
+    constructor(reason: "ATTRIBUTION_MISSING" | "BODY_HASH_MISMATCH" | "PROOF_INVALID" | "SIGNER_MISMATCH" | "SCOPE_MISMATCH" | "GRANT_MISMATCH" | "AUDIENCE_MISMATCH", message: string);
+}
+export interface StoredWriterAttributionVerification {
+    /** Signer recovered from the stored proof (equals the stored builder). */
+    builder: `0x${string}`;
+    grantId: string;
+    /** Hash re-derived from the stored data; equals the proof's bodyHash. */
+    bodyHash: string;
+    /** The signed claims (aud / method / uri / bodyHash / iat / exp). */
+    payload: Web3SignedPayload;
+}
+export interface VerifyStoredWriterAttributionOptions {
+    /**
+     * When known, the origin of the Personal Server the record was written to;
+     * the proof's signed audience must match it. Omit for records whose server
+     * is not known to the verifier.
+     */
+    expectedOrigin?: string;
+}
+/**
+ * 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 `$writtenBy`, 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 declare function verifyStoredWriterAttribution(envelope: {
+    scope: string;
+    data: Record<string, unknown>;
+}, options?: VerifyStoredWriterAttributionOptions): Promise<StoredWriterAttributionVerification>;
+//# sourceMappingURL=attribution.d.ts.map

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

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

package/dist/write/attribution.js

@@ -0,0 +1,277 @@
+/**
+ * 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 $writtenBy) 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";
+/** 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 `$writtenBy`, 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`);
+    }
+    const { [WRITER_ATTRIBUTION_KEY]: _attribution, ...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");
+    }
+    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"}