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

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.4.0",
+  "version": "1.6.0",
   "description": "Protocol logic for the Vana Personal Server — auth, grants, scopes, storage, keys",
   "license": "MIT",
   "repository": {
@@ -123,6 +123,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": {