@opendatalabs/personal-server-ts-core 0.0.1-canary.016adf9 → 0.0.1-canary.052d47e

package/dist/payment/x402.js

@@ -0,0 +1,402 @@
+/**
+ * X402 payment challenge / verification for builder reads.
+ *
+ * The personal server speaks an x402-style payment dance to builders on
+ * GET /v1/data/:scope. When a request arrives without (or with an invalid)
+ * X-PAYMENT header the server issues a 402 challenge: a server-signed
+ * RECORD_DATA_ACCESS attestation plus the canonical GenericPayment message
+ * the builder must EIP-712 sign. The builder retries with the signed
+ * message in X-PAYMENT; the server validates locally, then forwards to
+ * `POST /v1/escrow/pay` on the gateway. On 2xx the read proceeds; on
+ * 4xx/5xx the server responds with a fresh challenge.
+ *
+ * This module is wire-format only — it doesn't talk to the gateway or the
+ * storage layer. Callers in `api/index.ts` glue it to `gateway.getGrant`
+ * (for fee discovery), `IndexEntry.dataPointId/version` (for accessRecord
+ * binding), and a direct `fetch` to the gateway for payment forwarding.
+ */
+import { GENERIC_PAYMENT_TYPES, RECORD_DATA_ACCESS_TYPES, dataRegistryDomain, escrowPaymentDomain, } from "@opendatalabs/vana-sdk/browser";
+import { recoverTypedDataAddress } from "viem";
+// Per-event recordId on the access attestation. 32 cryptographically random
+// bytes — collision-resistant under the DataRegistryV2 `_usedRecordIds`
+// set the contract pins per access event.
+export function generateRecordId() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return ("0x" +
+        Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""));
+}
+// Build a fresh paymentNonce: high 32 bits = Date.now() (ms-monotonic), low
+// 32 bits = cryptographic randomness (within-ms collision avoidance). Yields
+// a strictly-increasing uint256 across ms ticks while keeping per-ms
+// collision probability negligible. Serialized as a decimal string on the
+// wire so the gateway's `^[1-9]\d*$` regex accepts it.
+//
+// Caveat: server-clock regressions can break monotonicity; the gateway
+// rejects out-of-order nonces with 409 and the builder retries.
+export function nextPaymentNonce() {
+    const rand = new Uint32Array(1);
+    crypto.getRandomValues(rand);
+    return (BigInt(Date.now()) << 32n) + BigInt(rand[0]);
+}
+// Recover the millisecond timestamp encoded in the high 32 bits of a nonce
+// generated by `nextPaymentNonce`. Used for the optional freshness check
+// during X-PAYMENT validation.
+export function paymentNonceIssueTimeMs(nonce) {
+    return nonce >> 32n;
+}
+const CHALLENGE_TTL_SECONDS = 300; // 5 min — challenges are stateless; this
+// is purely advisory for clients.
+const NONCE_FRESHNESS_MS = 600_000; // accept paymentNonces issued within
+// the last 10 minutes (or up to 1 min in the future — clock skew tolerance).
+const NONCE_FUTURE_SKEW_MS = 60_000;
+const BYTES32_REGEX = /^0x[0-9a-fA-F]{64}$/;
+const ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
+const SIGNATURE_REGEX = /^0x[0-9a-fA-F]{130}$/;
+const POSITIVE_DECIMAL_INT_REGEX = /^[1-9]\d*$/;
+const NON_NEGATIVE_DECIMAL_INT_REGEX = /^(0|[1-9]\d*)$/;
+export async function buildChallenge(input) {
+    const now = input.now?.() ?? new Date();
+    const expiresAt = Math.floor(now.getTime() / 1000) + CHALLENGE_TTL_SECONDS;
+    const generateNonce = input.generateNonce ?? nextPaymentNonce;
+    const generateRecord = input.generateRecordIdFn ?? generateRecordId;
+    // The canary `totalDue` already accounts for paymentStatus (registration
+    // is omitted when grant.paymentStatus === 'paid'). SDK comment: "snapshot
+    // — clients shouldn't cache across requests", so the caller re-fetches.
+    const amount = input.grant.fee.totalDue;
+    const registrationOwed = input.grant.paymentStatus !== "paid";
+    const asset = input.grant.fee.asset;
+    let accessRecord;
+    if (input.serverSigner &&
+        input.serverOwner &&
+        input.entry &&
+        input.entry.dataPointId !== null) {
+        const recordId = generateRecord();
+        const version = BigInt(input.entry.version);
+        const signature = await input.serverSigner.signRecordDataAccess({
+            ownerAddress: input.serverOwner,
+            scope: input.entry.scope,
+            version,
+            accessor: input.builder,
+            recordId,
+        });
+        accessRecord = {
+            dataPointId: input.entry.dataPointId,
+            version: version.toString(),
+            accessor: input.builder,
+            recordId,
+            signature,
+        };
+    }
+    const message = {
+        payerAddress: input.builder,
+        opType: "grant",
+        opId: input.grantId,
+        asset,
+        amount,
+        paymentNonce: generateNonce().toString(),
+    };
+    return {
+        x402Version: 1,
+        error: "PAYMENT_REQUIRED",
+        accepts: [
+            {
+                scheme: "vana-escrow-grant",
+                network: input.network,
+                asset,
+                amount,
+                domain: escrowPaymentDomain(input.gatewayConfig),
+                types: GENERIC_PAYMENT_TYPES,
+                message,
+                breakdown: {
+                    registrationFee: registrationOwed
+                        ? input.grant.fee.registrationFee
+                        : "0",
+                    dataAccessFee: input.grant.fee.dataAccessFee,
+                    registrationOwed,
+                },
+                ...(accessRecord ? { accessRecord } : {}),
+                expiresAt,
+            },
+        ],
+    };
+}
+// Decode base64 to UTF-8. Tolerates standard + url-safe alphabets so clients
+// can use either. Uses the universally-available `atob` + Web text codecs
+// rather than Node's Buffer so this module remains browser-safe (consumed
+// by ps-lite as well as the Node server).
+function base64decode(input) {
+    let s = input.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = (4 - (s.length % 4)) % 4;
+    s += "=".repeat(pad);
+    const binString = atob(s);
+    const bytes = Uint8Array.from(binString, (c) => c.codePointAt(0) ?? 0);
+    return new TextDecoder().decode(bytes);
+}
+function base64encode(input) {
+    const bytes = new TextEncoder().encode(input);
+    let binString = "";
+    for (const b of bytes)
+        binString += String.fromCodePoint(b);
+    return btoa(binString);
+}
+/**
+ * Parse the X-PAYMENT header value. Returns `null` if missing/malformed —
+ * the caller should treat that as "no payment provided" and issue a 402.
+ */
+export function parsePaymentHeader(headerValue) {
+    if (!headerValue)
+        return null;
+    let decoded;
+    try {
+        decoded = base64decode(headerValue.trim());
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    if (obj["x402Version"] !== 1)
+        return null;
+    if (obj["scheme"] !== "vana-escrow-grant")
+        return null;
+    if (typeof obj["network"] !== "string")
+        return null;
+    const payload = obj["payload"];
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const message = p["message"];
+    if (!message || typeof message !== "object")
+        return null;
+    const m = message;
+    if (typeof m["payerAddress"] !== "string" ||
+        !ADDRESS_REGEX.test(m["payerAddress"]) ||
+        typeof m["opType"] !== "string" ||
+        typeof m["opId"] !== "string" ||
+        !BYTES32_REGEX.test(m["opId"]) ||
+        typeof m["asset"] !== "string" ||
+        !ADDRESS_REGEX.test(m["asset"]) ||
+        typeof m["amount"] !== "string" ||
+        !NON_NEGATIVE_DECIMAL_INT_REGEX.test(m["amount"]) ||
+        typeof m["paymentNonce"] !== "string" ||
+        !POSITIVE_DECIMAL_INT_REGEX.test(m["paymentNonce"])) {
+        return null;
+    }
+    if (typeof p["signature"] !== "string" ||
+        !SIGNATURE_REGEX.test(p["signature"])) {
+        return null;
+    }
+    const accessRecordRaw = p["accessRecord"];
+    let accessRecord;
+    if (accessRecordRaw !== undefined) {
+        if (!accessRecordRaw || typeof accessRecordRaw !== "object")
+            return null;
+        const ar = accessRecordRaw;
+        if (typeof ar["dataPointId"] !== "string" ||
+            !BYTES32_REGEX.test(ar["dataPointId"]) ||
+            typeof ar["version"] !== "string" ||
+            !POSITIVE_DECIMAL_INT_REGEX.test(ar["version"]) ||
+            typeof ar["accessor"] !== "string" ||
+            !ADDRESS_REGEX.test(ar["accessor"]) ||
+            typeof ar["recordId"] !== "string" ||
+            !BYTES32_REGEX.test(ar["recordId"]) ||
+            typeof ar["signature"] !== "string" ||
+            !SIGNATURE_REGEX.test(ar["signature"])) {
+            return null;
+        }
+        accessRecord = {
+            dataPointId: ar["dataPointId"],
+            version: ar["version"],
+            accessor: ar["accessor"],
+            recordId: ar["recordId"],
+            signature: ar["signature"],
+        };
+    }
+    return {
+        x402Version: 1,
+        scheme: "vana-escrow-grant",
+        network: obj["network"],
+        payload: {
+            message: {
+                payerAddress: m["payerAddress"],
+                opType: m["opType"],
+                opId: m["opId"],
+                asset: m["asset"],
+                amount: m["amount"],
+                paymentNonce: m["paymentNonce"],
+            },
+            signature: p["signature"],
+            ...(accessRecord ? { accessRecord } : {}),
+        },
+    };
+}
+/**
+ * Encode an X402Payment back to a base64 header value. Useful for client
+ * code (the personal server only decodes here; this is exported for tests
+ * and downstream builders that want a shared serializer).
+ */
+export function encodePaymentHeader(payment) {
+    return base64encode(JSON.stringify(payment));
+}
+/**
+ * Validate a parsed X-PAYMENT against the live grant + entry state. On
+ * success the caller forwards the payment verbatim to the gateway. Any
+ * failure should result in a fresh 402 challenge.
+ *
+ * Replay defense is layered: gateway enforces per-(payer, opType, nonce)
+ * uniqueness via DB constraint and per-recordId uniqueness via the on-chain
+ * `_usedRecordIds` set. Local checks here catch obvious malformed echoes
+ * before they reach the gateway.
+ */
+export async function verifyPayment(input) {
+    const { payment, grant, builder } = input;
+    const msg = payment.payload.message;
+    // Builder identity: the payment must claim the authenticated signer.
+    // Recovery below cryptographically pins this.
+    if (msg.payerAddress.toLowerCase() !== builder.toLowerCase()) {
+        return {
+            ok: false,
+            reason: "payerAddress does not match authenticated builder",
+        };
+    }
+    if (msg.opType !== "grant") {
+        return { ok: false, reason: `Unsupported opType: ${msg.opType}` };
+    }
+    if (msg.opId.toLowerCase() !== input.grantId.toLowerCase()) {
+        return { ok: false, reason: "opId does not match the request's grantId" };
+    }
+    // Amount + asset must match the gateway's canonical values. Re-fetched
+    // per request, so a builder echoing stale amounts gets rejected here
+    // before we hit the gateway.
+    if (msg.asset.toLowerCase() !== grant.fee.asset.toLowerCase()) {
+        return { ok: false, reason: "asset does not match grant fee asset" };
+    }
+    if (msg.amount !== grant.fee.totalDue) {
+        return {
+            ok: false,
+            reason: `amount ${msg.amount} != grant.fee.totalDue ${grant.fee.totalDue}`,
+        };
+    }
+    // Stateless freshness check: extract the issue-time from the high 32 bits
+    // of paymentNonce and require it within the last ~10 minutes. Cheap; no
+    // server state. Catches replays of captured X-PAYMENTs far in the past.
+    let nonceBig;
+    try {
+        nonceBig = BigInt(msg.paymentNonce);
+    }
+    catch {
+        return { ok: false, reason: "paymentNonce is not a valid uint256" };
+    }
+    const issueMs = paymentNonceIssueTimeMs(nonceBig);
+    const nowMs = BigInt(input.nowMs?.() ?? Date.now());
+    if (issueMs > nowMs + BigInt(NONCE_FUTURE_SKEW_MS)) {
+        return { ok: false, reason: "paymentNonce timestamp is in the future" };
+    }
+    if (nowMs - issueMs > BigInt(NONCE_FRESHNESS_MS)) {
+        return {
+            ok: false,
+            reason: "paymentNonce is older than the freshness window",
+        };
+    }
+    // GenericPayment signature recovery — must recover to the builder.
+    let recoveredPayer;
+    try {
+        recoveredPayer = await recoverTypedDataAddress({
+            domain: escrowPaymentDomain(input.gatewayConfig),
+            types: GENERIC_PAYMENT_TYPES,
+            primaryType: "GenericPayment",
+            message: {
+                payerAddress: msg.payerAddress,
+                opType: msg.opType,
+                opId: msg.opId,
+                asset: msg.asset,
+                amount: BigInt(msg.amount),
+                paymentNonce: nonceBig,
+            },
+            signature: payment.payload.signature,
+        });
+    }
+    catch {
+        return { ok: false, reason: "GenericPayment signature recovery failed" };
+    }
+    if (recoveredPayer.toLowerCase() !== builder.toLowerCase()) {
+        return {
+            ok: false,
+            reason: "GenericPayment signer does not match authenticated builder",
+        };
+    }
+    // AccessRecord echo (when present) — verify the server actually signed it
+    // and the binding fields match the entry being served.
+    if (payment.payload.accessRecord) {
+        const ar = payment.payload.accessRecord;
+        if (!input.entry) {
+            return {
+                ok: false,
+                reason: "accessRecord supplied but no entry to bind it to",
+            };
+        }
+        if (input.entry.dataPointId === null) {
+            return {
+                ok: false,
+                reason: "accessRecord supplied but entry has no dataPointId yet",
+            };
+        }
+        if (ar.dataPointId.toLowerCase() !== input.entry.dataPointId.toLowerCase()) {
+            return {
+                ok: false,
+                reason: "accessRecord.dataPointId does not match entry",
+            };
+        }
+        if (ar.version !== String(input.entry.version)) {
+            return { ok: false, reason: "accessRecord.version does not match entry" };
+        }
+        if (ar.accessor.toLowerCase() !== builder.toLowerCase()) {
+            return {
+                ok: false,
+                reason: "accessRecord.accessor does not match authenticated builder",
+            };
+        }
+        if (!input.serverOwner) {
+            return {
+                ok: false,
+                reason: "serverOwner required to verify accessRecord signature",
+            };
+        }
+        let recoveredServer;
+        try {
+            recoveredServer = await recoverTypedDataAddress({
+                domain: dataRegistryDomain(input.gatewayConfig),
+                types: RECORD_DATA_ACCESS_TYPES,
+                primaryType: "RecordDataAccess",
+                message: {
+                    ownerAddress: input.serverOwner,
+                    scope: input.entry.scope,
+                    version: BigInt(ar.version),
+                    accessor: ar.accessor,
+                    recordId: ar.recordId,
+                },
+                signature: ar.signature,
+            });
+        }
+        catch {
+            return { ok: false, reason: "accessRecord signature recovery failed" };
+        }
+        if (recoveredServer.toLowerCase() !== input.serverAddress.toLowerCase()) {
+            return {
+                ok: false,
+                reason: "accessRecord signer is not this personal server",
+            };
+        }
+    }
+    return { ok: true, payment };
+}
+//# sourceMappingURL=x402.js.map

package/dist/payment/x402.js.map

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

package/dist/policy/data-read.d.ts

@@ -0,0 +1,32 @@
+import type { GatewayGrantResponse } from "@opendatalabs/vana-sdk/browser";
+import { type AuthSessionVerifierPort, type GrantVerifierPort, type RuntimeAvailabilityPort } from "../ports/index.js";
+export interface DataReadPolicyInput {
+    signer: `0x${string}`;
+    grantId?: string;
+    requestedScope: string;
+    fileId?: string;
+    /**
+     * This server's owner address. The grant's grantor MUST equal it — a grant
+     * issued by a different owner is rejected. Required (not optional) so that
+     * TypeScript flags any caller that fails to bind the read to the server
+     * owner; the check also fails closed at runtime for untyped/JS callers.
+     */
+    serverOwner: `0x${string}`;
+}
+export interface DataReadPolicyPorts {
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    runtimeAvailability?: RuntimeAvailabilityPort;
+}
+/**
+ * Parse a grant's `expiresAt` into unix seconds. Accepts the legacy
+ * uint256-seconds string, a numeric value, or the current gateway ISO
+ * timestamp. Returns 0 for "perpetual" encodings (null/undefined/"0") and
+ * null for unparseable input. Shared by the read and write policies so both
+ * stay aligned with the gateway response shape.
+ */
+export declare function parseGrantExpiresAtSeconds(value: unknown): number | null;
+/** Auth-result sentinels; see the reserved-grantId check below. */
+export declare const SENTINEL_GRANT_IDS: Set<string>;
+export declare function verifyDataReadPolicy(input: DataReadPolicyInput, ports: DataReadPolicyPorts): Promise<GatewayGrantResponse>;
+//# sourceMappingURL=data-read.d.ts.map

package/dist/policy/data-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-read.d.ts","sourceRoot":"","sources":["../../src/policy/data-read.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAa3E,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IAGvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,aAAa,EAAE,iBAAiB,CAAC;IAKjC,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUxE;AAED,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,aAAsC,CAAC;AAEtE,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAoH/B"}

package/dist/policy/data-read.js

@@ -0,0 +1,128 @@
+import { scopeCoveredByGrant } from "@opendatalabs/vana-sdk/browser";
+import { GrantExpiredError, GrantOwnerMismatchError, GrantRequiredError, GrantRevokedError, InvalidSignatureError, PsUnavailableError, ScopeMismatchError, ServerNotConfiguredError, UnregisteredBuilderError, } from "../errors/catalog.js";
+/**
+ * Parse a grant's `expiresAt` into unix seconds. Accepts the legacy
+ * uint256-seconds string, a numeric value, or the current gateway ISO
+ * timestamp. Returns 0 for "perpetual" encodings (null/undefined/"0") and
+ * null for unparseable input. Shared by the read and write policies so both
+ * stay aligned with the gateway response shape.
+ */
+export function parseGrantExpiresAtSeconds(value) {
+    if (value === null || value === undefined || value === "0")
+        return 0;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== "string")
+        return null;
+    const numeric = Number(value);
+    if (Number.isFinite(numeric))
+        return numeric;
+    const millis = Date.parse(value);
+    return Number.isNaN(millis) ? null : Math.floor(millis / 1000);
+}
+/** Auth-result sentinels; see the reserved-grantId check below. */
+export const SENTINEL_GRANT_IDS = new Set(["owner", "policy-bypass"]);
+export async function verifyDataReadPolicy(input, ports) {
+    const available = await ports.runtimeAvailability?.isAvailable();
+    if (available === false) {
+        throw new PsUnavailableError();
+    }
+    const builder = await ports.authSessionVerifier.getBuilder(input.signer);
+    if (!builder) {
+        throw new UnregisteredBuilderError();
+    }
+    if (!input.grantId) {
+        throw new GrantRequiredError({
+            reason: "No grantId in authorization payload",
+        });
+    }
+    // "owner" / "policy-bypass" are server-internal auth-result sentinels that
+    // confer the unredacted owner view and the x402 payment exemption. Neither
+    // caller input nor a gateway-supplied grant id may ever occupy them.
+    if (SENTINEL_GRANT_IDS.has(input.grantId)) {
+        throw new GrantRequiredError({
+            reason: "Reserved grantId",
+            grantId: input.grantId,
+        });
+    }
+    const grant = await ports.grantVerifier.getGrant(input.grantId);
+    if (!grant) {
+        throw new GrantRequiredError({
+            reason: "Grant not found",
+            grantId: input.grantId,
+        });
+    }
+    if (SENTINEL_GRANT_IDS.has(grant.id)) {
+        throw new GrantRequiredError({
+            reason: "Grant resolved to a reserved id",
+            grantId: input.grantId,
+        });
+    }
+    if (grant.revokedAt !== null) {
+        throw new GrantRevokedError({ grantId: grant.id });
+    }
+    // Canary GatewayGrantResponse is flat — scopes is a top-level string[]
+    // and expiresAt is a decimal-string uint256 (`null` = perpetual). The
+    // legacy signed `grant` JSON blob and `fileIds` pinning are gone.
+    if (!grant.scopes || grant.scopes.length === 0) {
+        throw new ScopeMismatchError({
+            requestedScope: input.requestedScope,
+            reason: "Grant has no scopes",
+        });
+    }
+    if (grant.expiresAt !== null && grant.expiresAt !== undefined) {
+        // DPv2 may surface either the legacy uint256-seconds string or the
+        // current gateway ISO timestamp. Parse both so the policy stays aligned
+        // with the gateway response shape.
+        const expiresAtSec = parseGrantExpiresAtSeconds(grant.expiresAt);
+        if (expiresAtSec === null) {
+            throw new ScopeMismatchError({
+                requestedScope: input.requestedScope,
+                reason: "Grant expiry is invalid",
+            });
+        }
+        if (expiresAtSec > 0) {
+            const nowSec = Math.floor(Date.now() / 1000);
+            if (expiresAtSec < nowSec) {
+                throw new GrantExpiredError({
+                    expiresAt: expiresAtSec,
+                });
+            }
+        }
+    }
+    if (!scopeCoveredByGrant(input.requestedScope, grant.scopes)) {
+        throw new ScopeMismatchError({
+            requestedScope: input.requestedScope,
+            grantedScopes: grant.scopes,
+        });
+    }
+    if (builder.id.toLowerCase() !== grant.granteeId.toLowerCase()) {
+        throw new InvalidSignatureError({
+            reason: "Request signer is not the grant builder",
+            expected: grant.granteeId,
+            actual: input.signer,
+        });
+    }
+    // Ownership binding — the grant MUST have been issued by THIS server's owner.
+    // Otherwise any PS holding the requested scope's data would serve it under a
+    // grant issued by a *different* owner (the happy-path binding is the app
+    // resolving the grantor's own PS via serverAddress — a convention, not an
+    // enforcement). Fail CLOSED: a missing serverOwner (server misconfig) or a
+    // grant with no grantor (gateway responses are untrusted runtime data,
+    // despite their type) must reject, never skip the check.
+    if (!input.serverOwner) {
+        throw new ServerNotConfiguredError({
+            reason: "serverOwner is required to verify grant ownership",
+        });
+    }
+    if (!grant.grantorAddress ||
+        grant.grantorAddress.toLowerCase() !== input.serverOwner.toLowerCase()) {
+        throw new GrantOwnerMismatchError({
+            grantId: grant.id,
+            expected: input.serverOwner,
+            actual: grant.grantorAddress ?? null,
+        });
+    }
+    return grant;
+}
+//# sourceMappingURL=data-read.js.map

package/dist/policy/data-read.js.map

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

package/dist/policy/data-write.d.ts

@@ -0,0 +1,69 @@
+import type { GatewayGrantResponse } from "@opendatalabs/vana-sdk/browser";
+import { type AuthSessionVerifierPort, type GrantVerifierPort, type RuntimeAvailabilityPort } from "../ports/index.js";
+/**
+ * Write-grant encoding: a grant scope entry prefixed with `write:` authorizes
+ * the grantee to WRITE into the scope it names (e.g. `write:notes.entries`,
+ * `write:notes.*`). The suffix uses the same pattern grammar as read scopes
+ * (`*` / `{prefix}.*` / exact), evaluated with the SDK's scopeMatchesPattern.
+ *
+ * Why a scope-entry prefix and not a new grant field: the gateway's grant
+ * shape (GatewayGrantResponse) has no permission axis — `scopes` is its only
+ * capability carrier — and the gateway validates scope entries as opaque
+ * non-empty strings, so `write:`-prefixed entries flow through createGrant /
+ * getGrant / the EIP-712 GrantRegistration signature unchanged. The Personal
+ * Server is the sole interpreter.
+ *
+ * Separation of powers falls out of the encoding:
+ *   - read policy matches the REQUESTED scope against grant entries verbatim
+ *     (scopeCoveredByGrant), and a requested scope never carries the prefix,
+ *     so `write:x` entries can never satisfy a read;
+ *   - write policy (below) only honors `write:`-prefixed entries, so plain
+ *     read entries can never satisfy a write.
+ */
+export declare const WRITE_SCOPE_PREFIX = "write:";
+export declare function isWriteScopeEntry(entry: string): boolean;
+/** The scope patterns a grant authorizes for writing (prefix stripped). */
+export declare function writeScopePatterns(grantScopes: readonly string[]): string[];
+export declare function scopeCoveredByWriteGrant(requestedScope: string, grantScopes: readonly string[]): boolean;
+/**
+ * Fee seam for builder writes. Write fee mechanics are undecided — the
+ * default (no port wired) is FREE. When a fee model lands (x402-style like
+ * reads, or something else), implement this port and wire it into
+ * DataWritePolicyPorts; the policy calls it after all authorization
+ * invariants pass, so a fee rejection never masks an auth failure.
+ */
+export interface WriteFeeVerifierPort {
+    assertWriteAllowed(input: {
+        builder: `0x${string}`;
+        grant: GatewayGrantResponse;
+        scope: string;
+    }): Promise<void>;
+}
+export interface DataWritePolicyInput {
+    signer: `0x${string}`;
+    grantId?: string;
+    requestedScope: string;
+    /**
+     * This server's owner address. The grant's grantor MUST equal it — a grant
+     * issued by a different owner is rejected. Required (not optional) so that
+     * TypeScript flags any caller that fails to bind the write to the server
+     * owner; the check also fails closed at runtime for untyped/JS callers.
+     */
+    serverOwner: `0x${string}`;
+}
+export interface DataWritePolicyPorts {
+    authSessionVerifier: AuthSessionVerifierPort;
+    grantVerifier: GrantVerifierPort;
+    runtimeAvailability?: RuntimeAvailabilityPort;
+    /** Absent = writes are free (see WriteFeeVerifierPort). */
+    writeFeeVerifier?: WriteFeeVerifierPort;
+}
+/**
+ * Authorize one builder write against a write-grant. Mirrors
+ * verifyDataReadPolicy invariant-for-invariant (builder registered, grant
+ * present / not revoked / not expired, scope coverage, grantee binding,
+ * owner binding) — but scope coverage only honors `write:`-prefixed grant
+ * entries, so a read-grant never confers write access.
+ */
+export declare function verifyDataWritePolicy(input: DataWritePolicyInput, ports: DataWritePolicyPorts): Promise<GatewayGrantResponse>;
+//# sourceMappingURL=data-write.d.ts.map