@opendatalabs/personal-server-ts-core 0.2.0 → 1.1.0

package/dist/api/index.d.ts

@@ -0,0 +1,160 @@
+import type { AccessLogWriter } from "../logging/access-log.js";
+import type { AccessLogReader } from "../logging/access-reader.js";
+import { type DataStoragePort, type RuntimeAvailabilityPort } from "../ports/index.js";
+import type { DataReadPolicyPorts } from "../policy/index.js";
+import type { SyncManager } from "../sync/index.js";
+import { type OAuthDeviceSessionLookup, type OAuthTokenStorePort } from "../contracts/index.js";
+import type { DataPortabilityGatewayConfig, GatewayClient } from "@opendatalabs/vana-sdk/browser";
+import type { ServerSigner } from "../signing/index.js";
+export interface PersonalServerReadAuthInput {
+    request: Request;
+    scope: string;
+    grantId?: string;
+    fileId?: string;
+}
+export interface PersonalServerReadAuthResult {
+    builder?: `0x${string}` | string;
+    grantId?: string;
+}
+export interface PersonalServerReadFulfillment {
+    builder: string;
+    fileId?: string;
+    grantId: string;
+    ipAddress: string;
+    logId: string;
+    scope: string;
+    servedAt: string;
+    userAgent: string;
+}
+export interface PersonalServerReadFulfillmentReporter {
+    report(event: PersonalServerReadFulfillment): Promise<void>;
+}
+export interface PersonalServerApiAuthPort {
+    authorizeOwner(request: Request): Promise<void>;
+    authorizeBuilderList(request: Request): Promise<void>;
+    authorizeBuilderRead(input: PersonalServerReadAuthInput): Promise<PersonalServerReadAuthResult | void>;
+}
+export interface PersonalServerApiLogger {
+    debug?(payload: Record<string, unknown>, message: string): void;
+    info?(payload: Record<string, unknown>, message: string): void;
+    warn?(payload: Record<string, unknown>, message: string): void;
+    error?(payload: Record<string, unknown>, message: string): void;
+}
+export interface PersonalServerIngestSyncManager {
+    trigger(): Promise<void>;
+    notifyNewData?(): void;
+    /** Propagate a scope deletion to R2 + the gateway before the local delete. */
+    deleteScopeRemote?(scope: string): Promise<void>;
+}
+export interface PersonalServerDataApiDeps {
+    storage: DataStoragePort;
+    auth: PersonalServerApiAuthPort;
+    accessLogWriter: AccessLogWriter;
+    syncManager?: PersonalServerIngestSyncManager | null;
+    runtimeAvailability?: RuntimeAvailabilityPort;
+    readFulfillmentReporter?: PersonalServerReadFulfillmentReporter;
+    /**
+     * Required when payment is on. Powers two things on GET /v1/data/:scope:
+     *   - the X402 challenge generation (fee lookup, accessRecord binding)
+     *   - the forward of validated X-PAYMENTs to gateway.payForOperation
+     *
+     * Two channels because the SDK client's payForOperation throws plain
+     * Errors on non-2xx and loses the gateway's structured error body — we
+     * need that body to map gateway 402/409/400 into fresh challenges.
+     */
+    gateway?: Pick<GatewayClient, "getGrant">;
+    /**
+     * Gateway base URL. Used for the direct-fetch forwarding of validated
+     * X-PAYMENTs to POST /v1/escrow/pay so we can inspect the gateway's
+     * structured error body (which the SDK's gateway.payForOperation
+     * discards). Required when X402 is enabled.
+     */
+    gatewayUrl?: string;
+    /**
+     * Required to construct escrowPaymentDomain + dataRegistryDomain for
+     * EIP-712 signature recovery during X-PAYMENT validation.
+     */
+    gatewayConfig?: DataPortabilityGatewayConfig;
+    /**
+     * Required for the X402 flow. Signs RECORD_DATA_ACCESS attestations
+     * embedded in 402 challenges. Without it, challenges still issue but
+     * never include an accessRecord — gateway accepts the resulting payment
+     * but the on-chain recordDataAccess won't be scheduled.
+     */
+    serverSigner?: Pick<ServerSigner, "signRecordDataAccess">;
+    serverOwner?: `0x${string}`;
+    /**
+     * The server's own account address — accessRecord signatures must
+     * recover to this for the X-PAYMENT validation to accept them as
+     * server-issued.
+     */
+    serverAddress?: `0x${string}`;
+    /**
+     * Identifier echoed in the X402 challenge as `accepts[].network`. Pure
+     * convention (e.g. "vana-moksha"); the gateway doesn't read it.
+     */
+    network?: string;
+    /**
+     * When true, GET /v1/data/:scope enforces the X402 dance: missing /
+     * invalid X-PAYMENT → 402 challenge; valid → forward to gateway then
+     * serve. When false (default), reads bypass payment entirely.
+     */
+    paymentEnabled?: boolean;
+    /**
+     * Test seam for the gateway forwarding fetch. Defaults to the global
+     * `fetch`; tests inject a mock that returns specific gateway statuses.
+     */
+    paymentFetch?: typeof fetch;
+    /**
+     * Test seam for the per-event recordId / paymentNonce / clock. Production
+     * leaves these unset and the X402 module generates fresh values via
+     * crypto.getRandomValues / Date.now.
+     */
+    generateRecordId?: () => `0x${string}`;
+    generatePaymentNonce?: () => bigint;
+    now?: () => Date;
+    createLogId?: () => string;
+    logger?: PersonalServerApiLogger;
+}
+export interface PersonalServerAccessLogsApiDeps {
+    auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;
+    accessLogReader: AccessLogReader;
+}
+export interface PersonalServerSyncApiDeps {
+    auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;
+    syncManager: Pick<SyncManager, "trigger" | "getStatus"> | null;
+    logger?: PersonalServerApiLogger;
+}
+export interface PersonalServerGrantsApiDeps {
+    auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;
+    gateway?: Pick<GatewayClient, "getBuilder" | "createGrant" | "listGrantsByUser" | "revokeGrant" | "getGrant">;
+    gatewayConfig?: DataPortabilityGatewayConfig;
+    serverOwner?: `0x${string}`;
+    serverSigner?: Pick<ServerSigner, "signGrantRegistration"> & Partial<Pick<ServerSigner, "signGrantRevocation">>;
+    now?: () => Date;
+}
+export interface PersonalServerConfigApiDeps {
+    auth: Pick<PersonalServerApiAuthPort, "authorizeOwner">;
+    readConfig(): Promise<unknown>;
+    writeConfig(config: unknown): Promise<void>;
+}
+export interface PersonalServerOauthTokenApiDeps {
+    tokenStore: OAuthTokenStorePort;
+    controlPlaneSecret?: string;
+    deviceSessions?: OAuthDeviceSessionLookup;
+    randomToken(): string;
+    now?: () => Date;
+    safeCompare?: (left: string, right: string) => boolean;
+}
+export interface PersonalServerApiDispatchOptions {
+    basePath?: string;
+}
+export declare function reportPersonalServerReadFulfillment(deps: PersonalServerDataApiDeps, event: PersonalServerReadFulfillment): void;
+export declare function handlePersonalServerDataRequest(request: Request, deps: PersonalServerDataApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
+export declare function handlePersonalServerAccessLogsRequest(request: Request, deps: PersonalServerAccessLogsApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
+export declare function handlePersonalServerSyncRequest(request: Request, deps: PersonalServerSyncApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
+export declare function handlePersonalServerGrantsRequest(request: Request, deps: PersonalServerGrantsApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
+export declare function handlePersonalServerConfigRequest(request: Request, deps: PersonalServerConfigApiDeps): Promise<Response>;
+export declare function handlePersonalServerOauthTokenRequest(request: Request, deps: PersonalServerOauthTokenApiDeps): Promise<Response>;
+export type { DataReadPolicyPorts };
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

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