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

package/dist/lineage/lineage.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Derivative data: lineage on the write path.
+ *
+ * A derivative is an ordinary write whose body names the data points it was
+ * computed from. The caller's `lineage` field (top level of a JSON body, or
+ * inside the `X-Vana-Metadata` object of a binary write) is a list of data
+ * point ids, `keccak256(abi.encode(owner, scope))`. The Personal Server
+ * validates it against the owner's own data points and mirrors it into the
+ * envelope `data` under the reserved `$lineage` key, the same in-`data`
+ * marker idiom as `$writtenBy` and `$binary`, so lineage rides the unchanged
+ * encrypt / upload / register path and `metadataHash` commits to it.
+ *
+ * The caller's `lineage` field is left in the record untouched: for session
+ * writes it is inside the bytes the builder signed, so the lineage claim is
+ * builder-signed and `$lineage` is the server-validated mirror of it.
+ *
+ * See docs/derivative-data-api.md for the wire contract.
+ */
+import type { DataStoragePort } from "../ports/index.js";
+/** Reserved key inside the envelope `data` record for validated lineage. */
+export declare const LINEAGE_KEY: "$lineage";
+/** The caller-facing field name (JSON body top level / binary metadata). */
+export declare const LINEAGE_FIELD: "lineage";
+/** Upper bound on sources per record; keeps validation and hashing bounded. */
+export declare const MAX_LINEAGE_SOURCES = 256;
+/** Page size of the local index scan the source resolver runs. */
+export declare const LOCAL_SCOPE_SCAN_PAGE = 1000;
+export interface StoredLineage {
+    /** Validated, lowercased source data point ids in the order given. */
+    sources: `0x${string}`[];
+    /** ISO timestamp the Personal Server validated and stamped the lineage. */
+    writtenAt: string;
+}
+/** A source as the resolver saw it (local index or gateway). */
+export interface ResolvedLineageSource {
+    dataPointId: `0x${string}`;
+    scope: string;
+    /** Null while the source is only known locally (not registered yet). */
+    version: string | null;
+    deletedAt: string | null;
+}
+/** The subset of a gateway data-point record the resolver needs. */
+export interface LineageDataPointRecord {
+    dataPointId: string;
+    ownerAddress: string;
+    scope: string;
+    version: string;
+    deletedAt: string | null;
+}
+/**
+ * Gateway lookup for a source that is not in the local index. Must include
+ * deleted (tombstoned) data points: a deleted source is still a valid
+ * lineage target, it is only reported as deleted when the lineage is walked.
+ */
+export interface LineageSourceLookup {
+    getDataPoint(dataPointId: string): Promise<LineageDataPointRecord | null>;
+}
+export declare function hasReservedLineageKey(data: Record<string, unknown>): boolean;
+/** Stamp validated lineage into an envelope `data` record. */
+export declare function stampLineage(data: Record<string, unknown>, lineage: StoredLineage): Record<string, unknown>;
+/**
+ * The stored `$lineage` of a record, or null for a root record. Tolerates
+ * hand-crafted envelopes: anything that is not the exact stamped shape is
+ * treated as no lineage rather than thrown on.
+ */
+export declare class StoredLineageMalformedError extends Error {
+    constructor(detail: string);
+}
+/**
+ * Absent `$lineage` (or a data object that is not a record) is `null`: no
+ * statement. A PRESENT but malformed `$lineage` throws: a corrupted or
+ * hand-crafted derivative must fail closed, never fall through the root
+ * path and get registered as if it made no lineage statement.
+ */
+export declare function readStoredLineage(data: Record<string, unknown> | undefined): StoredLineage | null;
+/**
+ * The caller's `lineage` field from a JSON body or a binary write's parsed
+ * metadata. `undefined` when the container is not an object or carries no
+ * such field, so a bare-string metadata header or a lineage-less body is a
+ * root record.
+ */
+export declare function extractLineageField(container: unknown): unknown;
+/**
+ * Parse the caller's `lineage` value: an array of distinct 0x-prefixed
+ * 32-byte hex strings, at most MAX_LINEAGE_SOURCES long. Ids are lowercased
+ * so equal ids compare equal wherever they are stored. Throws
+ * LineageInvalidError (400).
+ */
+export declare function parseLineageSources(value: unknown): `0x${string}`[];
+/** First dot-segment of a scope (`chatgpt` for `chatgpt.conversations`). */
+export declare function scopeNamespace(scope: string): string;
+/**
+ * The naming rule. Grant patterns are exact, `prefix.*` or `*`; `prefix.*`
+ * covers every scope that starts with `prefix.`. A derived scope and a
+ * source scope are both covered by the same non-universal pattern exactly
+ * when they share their first segment, and that is the one way the current
+ * grammar can leak across a lineage edge (a grant on `chatgpt.*` would read
+ * both `chatgpt.conversations` and a derivative named `chatgpt.summary`).
+ * `*` reads everything by definition and is not a lineage leak.
+ */
+export declare function derivedScopeViolatesNaming(derivedScope: string, sourceScope: string): boolean;
+export declare function assertDerivedScopeNaming(derivedScope: string, sourceScopes: readonly string[]): void;
+export interface ResolveLineageSourcesInput {
+    /** The derived record's scope. */
+    scope: string;
+    sources: readonly `0x${string}`[];
+    serverOwner: `0x${string}`;
+    storage: Pick<DataStoragePort, "listScopes">;
+    /** Absent = sources must be in the local index. */
+    gateway?: LineageSourceLookup;
+}
+/**
+ * Resolve every source id to a data point of this owner. The local index is
+ * consulted first (`keccak256(owner, scope)` over the server's own scopes,
+ * so an unsynced local scope is a valid source), then the gateway with
+ * deleted points included. An id that resolves to nothing, or to another
+ * owner's data point, fails the whole write with 422
+ * LINEAGE_SOURCE_UNKNOWN listing every offending id; a gateway that cannot
+ * be reached fails with 502 so the builder retries instead of being told
+ * its source does not exist.
+ */
+export declare function resolveLineageSources(input: ResolveLineageSourcesInput): Promise<ResolvedLineageSource[]>;
+export interface PrepareLineageInput {
+    scope: string;
+    /** The raw caller value (`body.lineage` / `metadata.lineage`). */
+    field: unknown;
+    serverOwner: `0x${string}` | undefined;
+    storage: Pick<DataStoragePort, "listScopes">;
+    gateway?: LineageSourceLookup;
+    now: () => Date;
+}
+/**
+ * Validate a write's lineage end to end (shape, sources, naming rule) and
+ * produce the `$lineage` record to stamp. An empty list is an EXPLICIT root
+ * statement: it is stamped (`sources: []`) and registered as an attested
+ * root, distinct from an absent field, which makes no lineage statement.
+ * Throws ProtocolErrors; callers on the write path let them propagate
+ * before anything is stored.
+ */
+export declare function prepareLineage(input: PrepareLineageInput): Promise<StoredLineage>;
+//# sourceMappingURL=lineage.d.ts.map

package/dist/lineage/lineage.d.ts.map

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

package/dist/lineage/lineage.js

@@ -0,0 +1,255 @@
+/**
+ * Derivative data: lineage on the write path.
+ *
+ * A derivative is an ordinary write whose body names the data points it was
+ * computed from. The caller's `lineage` field (top level of a JSON body, or
+ * inside the `X-Vana-Metadata` object of a binary write) is a list of data
+ * point ids, `keccak256(abi.encode(owner, scope))`. The Personal Server
+ * validates it against the owner's own data points and mirrors it into the
+ * envelope `data` under the reserved `$lineage` key, the same in-`data`
+ * marker idiom as `$writtenBy` and `$binary`, so lineage rides the unchanged
+ * encrypt / upload / register path and `metadataHash` commits to it.
+ *
+ * The caller's `lineage` field is left in the record untouched: for session
+ * writes it is inside the bytes the builder signed, so the lineage claim is
+ * builder-signed and `$lineage` is the server-validated mirror of it.
+ *
+ * See docs/derivative-data-api.md for the wire contract.
+ */
+import { LineageInvalidError, LineageScopeUnderSourcePrefixError, LineageSourceLookupFailedError, LineageSourceUnknownError, ServerNotConfiguredError, } from "../errors/catalog.js";
+import { computeDataPointId } from "../sync/data-point-id.js";
+/** Reserved key inside the envelope `data` record for validated lineage. */
+export const LINEAGE_KEY = "$lineage";
+/** The caller-facing field name (JSON body top level / binary metadata). */
+export const LINEAGE_FIELD = "lineage";
+/** Upper bound on sources per record; keeps validation and hashing bounded. */
+export const MAX_LINEAGE_SOURCES = 256;
+/** Page size of the local index scan the source resolver runs. */
+export const LOCAL_SCOPE_SCAN_PAGE = 1000;
+const BYTES32_HEX = /^0x[0-9a-fA-F]{64}$/;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function hasReservedLineageKey(data) {
+    return Object.prototype.hasOwnProperty.call(data, LINEAGE_KEY);
+}
+/** Stamp validated lineage into an envelope `data` record. */
+export function stampLineage(data, lineage) {
+    return { ...data, [LINEAGE_KEY]: lineage };
+}
+/**
+ * The stored `$lineage` of a record, or null for a root record. Tolerates
+ * hand-crafted envelopes: anything that is not the exact stamped shape is
+ * treated as no lineage rather than thrown on.
+ */
+export class StoredLineageMalformedError extends Error {
+    constructor(detail) {
+        super(`Stored $lineage is malformed: ${detail}`);
+        this.name = "StoredLineageMalformedError";
+    }
+}
+/**
+ * Absent `$lineage` (or a data object that is not a record) is `null`: no
+ * statement. A PRESENT but malformed `$lineage` throws: a corrupted or
+ * hand-crafted derivative must fail closed, never fall through the root
+ * path and get registered as if it made no lineage statement.
+ */
+export function readStoredLineage(data) {
+    if (!isRecord(data) || !(LINEAGE_KEY in data))
+        return null;
+    const value = data[LINEAGE_KEY];
+    if (!isRecord(value)) {
+        throw new StoredLineageMalformedError("not an object");
+    }
+    const sources = value.sources;
+    if (!Array.isArray(sources) ||
+        !sources.every((id) => typeof id === "string" && BYTES32_HEX.test(id))) {
+        throw new StoredLineageMalformedError("sources is not a list of bytes32 ids");
+    }
+    if (typeof value.writtenAt !== "string") {
+        throw new StoredLineageMalformedError("writtenAt is not a string");
+    }
+    return {
+        sources: sources.map((id) => id.toLowerCase()),
+        writtenAt: value.writtenAt,
+    };
+}
+/**
+ * The caller's `lineage` field from a JSON body or a binary write's parsed
+ * metadata. `undefined` when the container is not an object or carries no
+ * such field, so a bare-string metadata header or a lineage-less body is a
+ * root record.
+ */
+export function extractLineageField(container) {
+    if (!isRecord(container))
+        return undefined;
+    return container[LINEAGE_FIELD];
+}
+/**
+ * Parse the caller's `lineage` value: an array of distinct 0x-prefixed
+ * 32-byte hex strings, at most MAX_LINEAGE_SOURCES long. Ids are lowercased
+ * so equal ids compare equal wherever they are stored. Throws
+ * LineageInvalidError (400).
+ */
+export function parseLineageSources(value) {
+    if (!Array.isArray(value)) {
+        throw new LineageInvalidError(`${LINEAGE_FIELD} must be an array of data point ids (0x-prefixed 32-byte hex)`);
+    }
+    if (value.length > MAX_LINEAGE_SOURCES) {
+        throw new LineageInvalidError(`${LINEAGE_FIELD} lists ${value.length} sources; the maximum is ${MAX_LINEAGE_SOURCES}`, { max: MAX_LINEAGE_SOURCES, count: value.length });
+    }
+    const seen = new Set();
+    const sources = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !BYTES32_HEX.test(entry)) {
+            throw new LineageInvalidError(`${LINEAGE_FIELD} entries must be 0x-prefixed 32-byte hex data point ids`, { entry: typeof entry === "string" ? entry : typeof entry });
+        }
+        const id = entry.toLowerCase();
+        if (seen.has(id)) {
+            throw new LineageInvalidError(`${LINEAGE_FIELD} lists the same source twice`, { duplicate: id });
+        }
+        seen.add(id);
+        sources.push(id);
+    }
+    return sources;
+}
+/** First dot-segment of a scope (`chatgpt` for `chatgpt.conversations`). */
+export function scopeNamespace(scope) {
+    const dot = scope.indexOf(".");
+    return dot === -1 ? scope : scope.slice(0, dot);
+}
+/**
+ * The naming rule. Grant patterns are exact, `prefix.*` or `*`; `prefix.*`
+ * covers every scope that starts with `prefix.`. A derived scope and a
+ * source scope are both covered by the same non-universal pattern exactly
+ * when they share their first segment, and that is the one way the current
+ * grammar can leak across a lineage edge (a grant on `chatgpt.*` would read
+ * both `chatgpt.conversations` and a derivative named `chatgpt.summary`).
+ * `*` reads everything by definition and is not a lineage leak.
+ */
+export function derivedScopeViolatesNaming(derivedScope, sourceScope) {
+    return scopeNamespace(derivedScope) === scopeNamespace(sourceScope);
+}
+export function assertDerivedScopeNaming(derivedScope, sourceScopes) {
+    for (const sourceScope of sourceScopes) {
+        if (derivedScopeViolatesNaming(derivedScope, sourceScope)) {
+            throw new LineageScopeUnderSourcePrefixError({
+                scope: derivedScope,
+                sourceScope,
+            });
+        }
+    }
+}
+/**
+ * Resolve every source id to a data point of this owner. The local index is
+ * consulted first (`keccak256(owner, scope)` over the server's own scopes,
+ * so an unsynced local scope is a valid source), then the gateway with
+ * deleted points included. An id that resolves to nothing, or to another
+ * owner's data point, fails the whole write with 422
+ * LINEAGE_SOURCE_UNKNOWN listing every offending id; a gateway that cannot
+ * be reached fails with 502 so the builder retries instead of being told
+ * its source does not exist.
+ */
+export async function resolveLineageSources(input) {
+    const ownId = computeDataPointId(input.serverOwner, input.scope);
+    const self = input.sources.find((id) => id === ownId);
+    if (self) {
+        throw new LineageInvalidError("A record cannot list its own data point as a lineage source", { dataPointId: self });
+    }
+    const local = localScopesById(input.storage, input.serverOwner, new Set(input.sources));
+    const resolved = [];
+    const unknown = [];
+    for (const dataPointId of input.sources) {
+        const localScope = local.get(dataPointId);
+        if (localScope !== undefined) {
+            resolved.push({
+                dataPointId,
+                scope: localScope,
+                version: null,
+                deletedAt: null,
+            });
+            continue;
+        }
+        if (!input.gateway) {
+            unknown.push(dataPointId);
+            continue;
+        }
+        let record;
+        try {
+            record = await input.gateway.getDataPoint(dataPointId);
+        }
+        catch (err) {
+            throw new LineageSourceLookupFailedError({
+                dataPointId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        if (!record ||
+            record.ownerAddress.toLowerCase() !== input.serverOwner.toLowerCase()) {
+            unknown.push(dataPointId);
+            continue;
+        }
+        resolved.push({
+            dataPointId,
+            scope: record.scope,
+            version: record.version,
+            deletedAt: record.deletedAt,
+        });
+    }
+    if (unknown.length > 0) {
+        throw new LineageSourceUnknownError({ unknown });
+    }
+    return resolved;
+}
+/**
+ * `dataPointId -> scope` for the server's own scopes that appear in
+ * `wanted`. Pages through the whole local index (an unsynced scope is a
+ * valid source wherever it sorts), stopping early once every wanted id has
+ * been found.
+ */
+function localScopesById(storage, serverOwner, wanted) {
+    const byId = new Map();
+    for (let offset = 0;; offset += LOCAL_SCOPE_SCAN_PAGE) {
+        const { scopes, total } = storage.listScopes({
+            limit: LOCAL_SCOPE_SCAN_PAGE,
+            offset,
+        });
+        for (const summary of scopes) {
+            const id = computeDataPointId(serverOwner, summary.scope);
+            if (wanted.has(id))
+                byId.set(id, summary.scope);
+        }
+        if (byId.size === wanted.size ||
+            scopes.length === 0 ||
+            offset + scopes.length >= total) {
+            break;
+        }
+    }
+    return byId;
+}
+/**
+ * Validate a write's lineage end to end (shape, sources, naming rule) and
+ * produce the `$lineage` record to stamp. An empty list is an EXPLICIT root
+ * statement: it is stamped (`sources: []`) and registered as an attested
+ * root, distinct from an absent field, which makes no lineage statement.
+ * Throws ProtocolErrors; callers on the write path let them propagate
+ * before anything is stored.
+ */
+export async function prepareLineage(input) {
+    const sources = parseLineageSources(input.field);
+    if (!input.serverOwner) {
+        throw new ServerNotConfiguredError({
+            reason: "serverOwner is required to validate lineage sources",
+        });
+    }
+    const resolved = await resolveLineageSources({
+        scope: input.scope,
+        sources,
+        serverOwner: input.serverOwner,
+        storage: input.storage,
+        gateway: input.gateway,
+    });
+    assertDerivedScopeNaming(input.scope, resolved.map((source) => source.scope));
+    return { sources, writtenAt: input.now().toISOString() };
+}
+//# sourceMappingURL=lineage.js.map

package/dist/lineage/lineage.js.map

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

package/dist/logging/access-log.d.ts

@@ -2,7 +2,7 @@ export interface AccessLogEntry {
     logId: string;
     grantId: string;
     builder: string;
-    action: "read";
+    action: "read" | "write";
     scope: string;
     timestamp: string;
     ipAddress: string;

package/dist/logging/access-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-log.d.ts","sourceRoot":"","sources":["../../src/logging/access-log.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"access-log.d.ts","sourceRoot":"","sources":["../../src/logging/access-log.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

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

@@ -18,5 +18,13 @@ export interface DataReadPolicyPorts {
     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;
 export declare function verifyDataReadPolicy(input: DataReadPolicyInput, ports: DataReadPolicyPorts): Promise<GatewayGrantResponse>;
 //# sourceMappingURL=data-read.d.ts.map

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

@@ -1 +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;AAcD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAmG/B"}
+{"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,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAmG/B"}

package/dist/policy/data-read.js

@@ -1,6 +1,13 @@
 import { scopeCoveredByGrant } from "@opendatalabs/vana-sdk/browser";
 import { GrantExpiredError, GrantOwnerMismatchError, GrantRequiredError, GrantRevokedError, InvalidSignatureError, PsUnavailableError, ScopeMismatchError, ServerNotConfiguredError, UnregisteredBuilderError, } from "../errors/catalog.js";
-function parseExpiresAtSeconds(value) {
+/**
+ * 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")
@@ -50,7 +57,7 @@ export async function verifyDataReadPolicy(input, ports) {
         // 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 = parseExpiresAtSeconds(grant.expiresAt);
+        const expiresAtSec = parseGrantExpiresAtSeconds(grant.expiresAt);
         if (expiresAtSec === null) {
             throw new ScopeMismatchError({
                 requestedScope: input.requestedScope,

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-write.d.ts","sourceRoot":"","sources":["../../src/policy/data-write.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;AAG3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAK3E;AAED,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAIT;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,kBAAkB,CAAC,KAAK,EAAE;QACxB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;QACvB,KAAK,EAAE,oBAAoB,CAAC;QAC5B,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,uBAAuB,CAAC;IAC7C,aAAa,EAAE,iBAAiB,CAAC;IACjC,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,oBAAoB,EAC3B,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAkG/B"}