@opendatalabs/personal-server-ts-core 1.10.2 → 1.11.0

package/dist/write/authorize.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Delegated-write authorization, shared by every build.
+ *
+ * `authorizeWrite` / `authorizeWriteSession` are the two write-session halves
+ * of `PersonalServerApiAuthPort`. They were originally written inside the Node
+ * server's auth adapter (packages/server/src/api-auth.ts); the checks they run
+ * are pure protocol — a token hash, a live grant re-check, an EIP-191 payload
+ * proof and a replay reservation — with nothing Node-specific in them, so they
+ * live here and BOTH the Node server adapter and the browser (PS-Lite)
+ * adapters call the same code. There is exactly one implementation of the
+ * write policy; a browser build cannot drift into a weaker one.
+ *
+ * The two entry points differ in what they are allowed to decide:
+ *
+ *   - `authorizeSessionWrite` authorizes a write to a NAMED scope. It
+ *     re-runs `verifyDataWritePolicy` against the LIVE grant on every call,
+ *     so revocation, expiry, grantee binding, owner binding and scope
+ *     coverage stay authoritative per write rather than being frozen at
+ *     handshake, and it verifies the builder's per-write payload proof.
+ *   - `recognizeWriteSession` is identity only: the bearer must resolve to a
+ *     live session and the request must carry that builder's valid proof, but
+ *     NO grant policy runs (there is no scope to run one against). Callers use
+ *     it only to choose between error shapes, never to release data.
+ *
+ * Both fail closed: an unknown bearer, an unknown session, a missing server
+ * owner, or any failing proof check returns/raises rather than falling back to
+ * a weaker credential. A request that is not a write-session request at all
+ * returns `undefined`, and the caller applies its own owner gate.
+ */
+import { ProtocolError } from "../errors/catalog.js";
+import { type DataWritePolicyPorts } from "../policy/data-write.js";
+import type { PersonalServerWriteAuthInput, PersonalServerWriteAuthResult, PersonalServerWriteSessionResult } from "../api/index.js";
+import { type WriteProofReplayStore, type WriteSessionStore } from "./session.js";
+export interface WriteSessionAuthorizationDeps {
+    /**
+     * This server's origin. Every payload proof must name it as its audience,
+     * so a proof signed for another Personal Server cannot be relayed here.
+     */
+    serverOrigin: string | (() => string);
+    /**
+     * The owner every grant must have been issued by. Absent = fail closed:
+     * a delegated write cannot be bound to an owner we cannot name.
+     */
+    serverOwner?: `0x${string}`;
+    /**
+     * Live write sessions (minted by POST /v1/write/session). Absent = the host
+     * does not support delegated writes and every request falls through to the
+     * caller's owner gate.
+     */
+    sessionStore?: WriteSessionStore;
+    /** Replay guard for the per-write `X-Vana-Write-Signature` proofs. */
+    replayStore: WriteProofReplayStore;
+    /** Live builder/grant verification, re-run on every delegated write. */
+    policyPorts: DataWritePolicyPorts;
+    now?: () => Date;
+}
+export interface WriteSessionAuthorization {
+    /**
+     * Authorize a delegated write to `input.scope`, or `undefined` when the
+     * request carries no live write-session credential (the caller then applies
+     * its owner gate, exactly as before write sessions existed).
+     */
+    authorizeSessionWrite(input: PersonalServerWriteAuthInput): Promise<PersonalServerWriteAuthResult | undefined>;
+    /**
+     * Identity-only recognition of a write-session caller. Never releases data.
+     */
+    recognizeWriteSession(request: Request): Promise<PersonalServerWriteSessionResult | undefined>;
+}
+/** The bearer credential a write session is presented under. */
+export declare function writeSessionBearerToken(request: Request): string | null;
+/**
+ * Same shape and message as the auth layer's own missing-owner failure, so a
+ * host that never configured an owner reports one thing, not two.
+ */
+export declare function writeServerNotConfigured(): ProtocolError;
+export declare function createWriteSessionAuthorization(deps: WriteSessionAuthorizationDeps): WriteSessionAuthorization;
+//# sourceMappingURL=authorize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.d.ts","sourceRoot":"","sources":["../../src/write/authorize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC7B,gCAAgC,EACjC,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACtC;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,sEAAsE;IACtE,WAAW,EAAE,qBAAqB,CAAC;IACnC,wEAAwE;IACxE,WAAW,EAAE,oBAAoB,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,qBAAqB,CACnB,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,6BAA6B,GAAG,SAAS,CAAC,CAAC;IACtD;;OAEG;IACH,qBAAqB,CACnB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC,CAAC;CAC1D;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,aAAa,CAMxD;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,6BAA6B,GAClC,yBAAyB,CA6D3B"}

package/dist/write/authorize.js

@@ -0,0 +1,109 @@
+/**
+ * Delegated-write authorization, shared by every build.
+ *
+ * `authorizeWrite` / `authorizeWriteSession` are the two write-session halves
+ * of `PersonalServerApiAuthPort`. They were originally written inside the Node
+ * server's auth adapter (packages/server/src/api-auth.ts); the checks they run
+ * are pure protocol — a token hash, a live grant re-check, an EIP-191 payload
+ * proof and a replay reservation — with nothing Node-specific in them, so they
+ * live here and BOTH the Node server adapter and the browser (PS-Lite)
+ * adapters call the same code. There is exactly one implementation of the
+ * write policy; a browser build cannot drift into a weaker one.
+ *
+ * The two entry points differ in what they are allowed to decide:
+ *
+ *   - `authorizeSessionWrite` authorizes a write to a NAMED scope. It
+ *     re-runs `verifyDataWritePolicy` against the LIVE grant on every call,
+ *     so revocation, expiry, grantee binding, owner binding and scope
+ *     coverage stay authoritative per write rather than being frozen at
+ *     handshake, and it verifies the builder's per-write payload proof.
+ *   - `recognizeWriteSession` is identity only: the bearer must resolve to a
+ *     live session and the request must carry that builder's valid proof, but
+ *     NO grant policy runs (there is no scope to run one against). Callers use
+ *     it only to choose between error shapes, never to release data.
+ *
+ * Both fail closed: an unknown bearer, an unknown session, a missing server
+ * owner, or any failing proof check returns/raises rather than falling back to
+ * a weaker credential. A request that is not a write-session request at all
+ * returns `undefined`, and the caller applies its own owner gate.
+ */
+import { ProtocolError } from "../errors/catalog.js";
+import { verifyDataWritePolicy, } from "../policy/data-write.js";
+import { verifyWriterAttribution } from "./attribution.js";
+import { hashWriteSessionToken, } from "./session.js";
+/** The bearer credential a write session is presented under. */
+export function writeSessionBearerToken(request) {
+    const header = request.headers.get("authorization");
+    if (!header?.startsWith("Bearer "))
+        return null;
+    return header.slice(7);
+}
+/**
+ * Same shape and message as the auth layer's own missing-owner failure, so a
+ * host that never configured an owner reports one thing, not two.
+ */
+export function writeServerNotConfigured() {
+    return new ProtocolError(500, "SERVER_NOT_CONFIGURED", "Server owner address not configured. Set VANA_MASTER_KEY_SIGNATURE environment variable.");
+}
+export function createWriteSessionAuthorization(deps) {
+    async function liveSession(request) {
+        const token = writeSessionBearerToken(request);
+        if (!token || !deps.sessionStore)
+            return null;
+        return deps.sessionStore.getByTokenHash(await hashWriteSessionToken(token));
+    }
+    return {
+        async authorizeSessionWrite(input) {
+            const session = await liveSession(input.request);
+            if (!session)
+                return undefined;
+            if (!deps.serverOwner)
+                throw writeServerNotConfigured();
+            // The grant is re-checked live on EVERY write: a session token minted
+            // an hour ago against a grant that has since been revoked, narrowed or
+            // expired authorizes nothing.
+            const grant = await verifyDataWritePolicy({
+                signer: session.builderAddress,
+                grantId: session.grantId,
+                requestedScope: input.scope,
+                serverOwner: deps.serverOwner,
+            }, deps.policyPorts);
+            // releaseProof is a rollback hook for the handler, never part of the
+            // stored attribution record.
+            const { releaseProof, ...attribution } = await verifyWriterAttribution({
+                request: input.request,
+                builderAddress: session.builderAddress,
+                grantId: grant.id,
+                serverOrigin: deps.serverOrigin,
+                replayStore: deps.replayStore,
+                now: deps.now,
+            });
+            return {
+                builder: session.builderAddress,
+                grantId: grant.id,
+                grantScopes: grant.scopes ?? [],
+                attribution,
+                releaseProof,
+            };
+        },
+        async recognizeWriteSession(request) {
+            const session = await liveSession(request);
+            if (!session)
+                return undefined;
+            const { releaseProof } = await verifyWriterAttribution({
+                request,
+                builderAddress: session.builderAddress,
+                grantId: session.grantId,
+                serverOrigin: deps.serverOrigin,
+                replayStore: deps.replayStore,
+                now: deps.now,
+            });
+            return {
+                builder: session.builderAddress,
+                grantId: session.grantId,
+                releaseProof,
+            };
+        },
+    };
+}
+//# sourceMappingURL=authorize.js.map

package/dist/write/authorize.js.map

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

package/dist/write/index.d.ts

@@ -1,3 +1,5 @@
 export { createInMemoryWriteProofReplayStore, createInMemoryWriteSessionStore, createWriteSession, hashWriteSessionToken, type CreateWriteSessionInput, type CreateWriteSessionOptions, type CreateWriteSessionResult, type WriteProofReplayStore, type WriteSessionRecord, type WriteSessionStore, } from "./session.js";
+export { createWriteSessionAuthorization, writeServerNotConfigured, writeSessionBearerToken, type WriteSessionAuthorization, type WriteSessionAuthorizationDeps, } from "./authorize.js";
+export { handleWriteSessionRequest, type HandleWriteSessionRequestDeps, type WriteSessionResponseBody, type WriteSessionRouteLogger, } from "./route.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

@@ -1 +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"}
+{"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,+BAA+B,EAC/B,wBAAwB,EACxB,uBAAuB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,GACnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,KAAK,6BAA6B,EAClC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AACpB,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

@@ -1,3 +1,5 @@
 export { createInMemoryWriteProofReplayStore, createInMemoryWriteSessionStore, createWriteSession, hashWriteSessionToken, } from "./session.js";
+export { createWriteSessionAuthorization, writeServerNotConfigured, writeSessionBearerToken, } from "./authorize.js";
+export { handleWriteSessionRequest, } from "./route.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

@@ -1 +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"}
+{"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,+BAA+B,EAC/B,wBAAwB,EACxB,uBAAuB,GAGxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,GAI1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,kCAAkC,GAOnC,MAAM,kBAAkB,CAAC"}

package/dist/write/route.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The write-session handshake, as a runtime-agnostic request handler.
+ *
+ * `POST /v1/write/session`: a registered builder proves control of its key and
+ * of a write-grant with a Web3Signed proof (the same handshake shape as the
+ * self-signing MCP session) and gets a short-lived bearer token. That token
+ * then gates delegated writes on the EXISTING ingest endpoint
+ * (`POST /v1/data/:scope`) and the derivative question routes. The Personal
+ * Server keeps signing AddData as the owner; the builder never holds the owner
+ * key.
+ *
+ * This lived in the Node server as a Hono route (packages/server/src/routes/
+ * write-session.ts) and reached for `node:crypto` for two things: a sha-256 of
+ * the proof header, and 32 random bytes for the token. Both have Web Crypto
+ * equivalents, so the handshake is expressed here over plain `Request` /
+ * `Response` and BOTH builds mount the same handler — the Node route is a Hono
+ * wrapper around it, and the browser runtime dispatches to it directly. There
+ * is one implementation of who may open a write session.
+ */
+import type { SessionTokenVerifierPort } from "../auth/index.js";
+import type { AuthSessionVerifierPort, GrantVerifierPort } from "../ports/index.js";
+import { type WriteProofReplayStore, type WriteSessionStore } from "./session.js";
+export interface WriteSessionRouteLogger {
+    info?(payload: Record<string, unknown>, message: string): void;
+    error?(payload: Record<string, unknown>, message: string): void;
+}
+export interface HandleWriteSessionRequestDeps {
+    serverOrigin: string | (() => string);
+    serverOwner?: `0x${string}`;
+    /**
+     * The store the redeeming routes read from. One store is wired into the
+     * handshake and into the API auth adapter; see createApp / the PS-Lite
+     * runtime.
+     */
+    sessionStore: WriteSessionStore;
+    /** Replay guard for the HANDSHAKE proof (distinct from per-write proofs). */
+    replayStore?: WriteProofReplayStore;
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    devToken?: string;
+    accessToken?: string;
+    tokenStore?: SessionTokenVerifierPort;
+    /** Overridable for tests; defaults to `vana_write_` + 32 random bytes. */
+    randomToken?: () => string;
+    ttlMs?: number;
+    now?: () => number;
+    logger?: WriteSessionRouteLogger;
+}
+export interface WriteSessionResponseBody {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    /** Write patterns, `write:` prefix stripped. */
+    scope: string;
+}
+/**
+ * Handle one `POST /v1/write/session` request. The caller has already matched
+ * the method and path; anything reaching here is treated as the handshake.
+ */
+export declare function handleWriteSessionRequest(request: Request, deps: HandleWriteSessionRequestDeps): Promise<Response>;
+//# sourceMappingURL=route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/write/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAGjE,OAAO,KAAK,EACV,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/D,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,aAAa,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,QAAQ,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;CACf;AA2CD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,6BAA6B,GAClC,OAAO,CAAC,QAAQ,CAAC,CA4GnB"}

package/dist/write/route.js

@@ -0,0 +1,132 @@
+/**
+ * The write-session handshake, as a runtime-agnostic request handler.
+ *
+ * `POST /v1/write/session`: a registered builder proves control of its key and
+ * of a write-grant with a Web3Signed proof (the same handshake shape as the
+ * self-signing MCP session) and gets a short-lived bearer token. That token
+ * then gates delegated writes on the EXISTING ingest endpoint
+ * (`POST /v1/data/:scope`) and the derivative question routes. The Personal
+ * Server keeps signing AddData as the owner; the builder never holds the owner
+ * key.
+ *
+ * This lived in the Node server as a Hono route (packages/server/src/routes/
+ * write-session.ts) and reached for `node:crypto` for two things: a sha-256 of
+ * the proof header, and 32 random bytes for the token. Both have Web Crypto
+ * equivalents, so the handshake is expressed here over plain `Request` /
+ * `Response` and BOTH builds mount the same handler — the Node route is a Hono
+ * wrapper around it, and the browser runtime dispatches to it directly. There
+ * is one implementation of who may open a write session.
+ */
+import { authenticateRequest } from "../auth/index.js";
+import { ProtocolError } from "../errors/catalog.js";
+import { hashConnectionToken } from "../mcp/connection-api.js";
+import { createWriteSession, } from "./session.js";
+function jsonError(status, errorCode, message) {
+    return { error: { code: status, errorCode, message } };
+}
+function jsonResponse(body, status) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/**
+ * Only ProtocolErrors are client-facing. Anything else (gateway, store,
+ * runtime failures) is logged with its cause and answered generically so
+ * internal details never reach the caller. Same mapping as the core data
+ * handler.
+ */
+function internalError(logger, err, stage) {
+    logger?.error?.({ err, stage }, "Write session handshake failed with an unexpected error");
+    return jsonResponse(jsonError(500, "INTERNAL_ERROR", "Internal server error"), 500);
+}
+function defaultRandomToken() {
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `vana_write_${hex}`;
+}
+/**
+ * Handle one `POST /v1/write/session` request. The caller has already matched
+ * the method and path; anything reaching here is treated as the handshake.
+ */
+export async function handleWriteSessionRequest(request, deps) {
+    // Fail closed: minting a session requires this server's owner to bind the
+    // grant to (createWriteSession rejects wrong-owner grants).
+    if (!deps.serverOwner) {
+        return jsonResponse(jsonError(500, "SERVER_NOT_CONFIGURED", "Server owner is not configured"), 500);
+    }
+    let authResult;
+    try {
+        authResult = await authenticateRequest({
+            request,
+            serverOrigin: deps.serverOrigin,
+            devToken: deps.devToken,
+            accessToken: deps.accessToken,
+            sessionTokenVerifier: deps.tokenStore,
+            serverOwner: deps.serverOwner,
+        });
+    }
+    catch (err) {
+        if (!(err instanceof ProtocolError)) {
+            return internalError(deps.logger, err, "authenticate");
+        }
+        return jsonResponse(jsonError(401, "WRITE_SESSION_AUTH_FAILED", err.message), 401);
+    }
+    // A bearer credential (dev token, control-plane token, CLI session) proves
+    // nothing about the builder's key, so it can never open a write session.
+    if (authResult.mechanism !== "web3-signed") {
+        return jsonResponse(jsonError(401, "WRITE_SESSION_PROOF_REQUIRED", "POST /v1/write/session requires a Web3Signed proof signed by the builder key"), 401);
+    }
+    const grantId = authResult.auth.payload.grantId;
+    if (!grantId) {
+        return jsonResponse(jsonError(400, "GRANT_ID_REQUIRED", "The Web3Signed proof must carry a grantId (the write-grant issued to the builder)"), 400);
+    }
+    // Replay guard: bind to a digest of the exact proof header, remembered
+    // until the proof's own expiry (a replay only matters while still valid).
+    const proofHeader = request.headers.get("authorization") ?? "";
+    const proofId = await hashConnectionToken(proofHeader);
+    const expSec = authResult.auth.payload.exp;
+    const expiresAtMs = (typeof expSec === "number"
+        ? expSec
+        : Math.floor(Date.now() / 1000) + 300) * 1000;
+    try {
+        const session = await createWriteSession({
+            builderAddress: authResult.auth.signer,
+            grantId,
+            proof: { id: proofId, expiresAtMs },
+        }, {
+            store: deps.sessionStore,
+            authSessionVerifier: deps.authSessionVerifier,
+            grantVerifier: deps.grantVerifier,
+            serverOwner: deps.serverOwner,
+            randomToken: deps.randomToken ?? defaultRandomToken,
+            ...(deps.ttlMs === undefined ? {} : { ttlMs: deps.ttlMs }),
+            ...(deps.now === undefined ? {} : { now: deps.now }),
+            ...(deps.replayStore === undefined
+                ? {}
+                : { replayStore: deps.replayStore }),
+        });
+        deps.logger?.info?.({
+            builder: authResult.auth.signer,
+            grantId: session.grantId,
+            writeScopes: session.writeScopes,
+        }, "Write session minted");
+        const body = {
+            access_token: session.accessToken,
+            token_type: "Bearer",
+            expires_in: session.expiresInSeconds,
+            // Write patterns, prefix stripped — what POST /v1/data/:scope will
+            // accept under this token.
+            scope: session.writeScopes.join(" "),
+        };
+        return jsonResponse(body, 200);
+    }
+    catch (err) {
+        if (err instanceof ProtocolError) {
+            return jsonResponse(err.toJSON(), err.code);
+        }
+        return internalError(deps.logger, err, "create-session");
+    }
+}
+//# sourceMappingURL=route.js.map

package/dist/write/route.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/personal-server-ts-core",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "Protocol logic for the Vana Personal Server — auth, grants, scopes, storage, keys",
   "license": "MIT",
   "repository": {