stellarium-ts 0.12.0 → 0.14.0

package/dist/resource/invoker.d.ts

@@ -1,4 +1,5 @@
 import { Resource, ResourceFunctionCallParameter, ResourceInvoker } from "requestscript";
+import type { GrantService } from "../grant/service.js";
 import { ResourceRepository } from "./repository.js";
 export interface PaymentVoucher {
     requestId: string;
@@ -7,33 +8,44 @@ export interface PaymentVoucher {
     recipientAddress: string;
     signature: string;
     expiresAt: string;
+    invocationHash: string;
     publicKey: string;
 }
 /**
- * The object `createPaymentVoucher` signs. `signature` is excluded, and
- * `resourcePath`, `resourceName`, and `parameters` come from the invocation,
- * not from the voucher itself. Key order is part of the signed bytes.
+ * Hash binding a voucher to one function call. Providers recompute it from the
+ * request they receive and compare it to `voucher.invocationHash`.
+ * Key order is part of the hashed bytes.
  */
-export declare function paymentVoucherPayload(voucher: Omit<PaymentVoucher, "signature">, resourcePath: string, resourceName: string, parameters: ResourceFunctionCallParameter[]): {
+export declare function invocationHash(resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): string;
+/**
+ * The object `createPaymentVoucher` signs: every voucher field except `signature`.
+ * Key order is part of the signed bytes.
+ */
+export declare function paymentVoucherPayload(voucher: Omit<PaymentVoucher, "signature">): {
     requestId: string;
     invocationId: string;
     amount: number;
     recipientAddress: string;
     expiresAt: string;
-    resourcePath: string;
-    resourceName: string;
-    parameters: ResourceFunctionCallParameter[];
+    invocationHash: string;
     publicKey: string;
 };
+export declare const EXTERNAL_INVOKE_MAX_RETRIES = 3;
+export declare const EXTERNAL_INVOKE_BASE_DELAY_MS = 500;
+/** Per attempt. A timed-out attempt is retried like a network error. */
+export declare const EXTERNAL_INVOKE_TIMEOUT_MS = 30000;
 export declare class CombinationResourceInvoker implements ResourceInvoker {
     private readonly resourceRepository;
     private readonly costLimitLamports;
     private readonly publicKey;
     private readonly privateKey;
-    constructor(resourceRepository: ResourceRepository, costLimitLamports: number, publicKey: string, privateKey: string);
+    private readonly grantService?;
+    /** Without a `grantService`, calls to restricted remote functions fail. */
+    constructor(resourceRepository: ResourceRepository, costLimitLamports: number, publicKey: string, privateKey: string, grantService?: GrantService | undefined);
     /**
      * Invoke a function on a resource.
      * If the resource has a baseUrl, it will be invoked as a remote function.
+     * If the function is restricted, it attaches an authorization from a held grant.
      * If the resource has a paymentManifest, it will create a payment voucher and pass it to the resource.
      * Otherwise, it will be invoked as a local function.
      *
@@ -48,6 +60,6 @@ export declare class CombinationResourceInvoker implements ResourceInvoker {
             message: string;
         } | null;
     }>;
-    createPaymentVoucher(recipientAddress: string, amount: number, resourcePath: string, resourceName: string, parameters: ResourceFunctionCallParameter[]): PaymentVoucher;
+    createPaymentVoucher(recipientAddress: string, amount: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): PaymentVoucher;
 }
 //# sourceMappingURL=invoker.d.ts.map

package/dist/resource/invoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,EAC1C,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,6BAA6B,EAAE;;;;;;;;;;EAI9C;AAED,qBAAa,0BAA2B,YAAW,eAAe;IAElD,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAAsB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAAU,OAAO,CAAC,QAAQ,CAAC,SAAS;IAAU,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAhL,YAA6B,kBAAkB,EAAE,kBAAkB,EAAmB,iBAAiB,EAAE,MAAM,EAAmB,SAAS,EAAE,MAAM,EAAmB,UAAU,EAAE,MAAM,EAAI;IAC5L;;;;;;;;;;OAUG;IACG,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAC,CAAC,CAmD7J;IAED,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,cAAc,CAOtK;CACJ"}
+{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,6BAA6B,EAAE,GAC5C,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC;;;;;;;;EAG/E;AAED,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,QAAS,CAAC;AA2BjD,qBAAa,0BAA2B,YAAW,eAAe;IAGlD,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAAsB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAAU,OAAO,CAAC,QAAQ,CAAC,SAAS;IAAU,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAU,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IADxN,2EAA2E;IAC3E,YAA6B,kBAAkB,EAAE,kBAAkB,EAAmB,iBAAiB,EAAE,MAAM,EAAmB,SAAS,EAAE,MAAM,EAAmB,UAAU,EAAE,MAAM,EAAmB,YAAY,CAAC,EAAE,YAAY,YAAA,EAAI;IAC1O;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAC,CAAC,CAgE7J;IAED,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,cAAc,CAQ5L;CACJ"}

package/dist/resource/invoker.js

@@ -1,27 +1,67 @@
-import { signData } from "../crypto/utils.js";
+import { hashData, signData } from "../crypto/utils.js";
 /**
- * The object `createPaymentVoucher` signs. `signature` is excluded, and
- * `resourcePath`, `resourceName`, and `parameters` come from the invocation,
- * not from the voucher itself. Key order is part of the signed bytes.
+ * Hash binding a voucher to one function call. Providers recompute it from the
+ * request they receive and compare it to `voucher.invocationHash`.
+ * Key order is part of the hashed bytes.
  */
-export function paymentVoucherPayload(voucher, resourcePath, resourceName, parameters) {
-    const { requestId, invocationId, amount, recipientAddress, expiresAt, publicKey } = voucher;
-    return { requestId, invocationId, amount, recipientAddress, expiresAt, resourcePath, resourceName, parameters, publicKey };
+export function invocationHash(resourcePath, resourceName, functionName, parameters) {
+    return hashData({ resourcePath, resourceName, functionName, parameters });
+}
+/**
+ * The object `createPaymentVoucher` signs: every voucher field except `signature`.
+ * Key order is part of the signed bytes.
+ */
+export function paymentVoucherPayload(voucher) {
+    const { requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash, publicKey } = voucher;
+    return { requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash, publicKey };
+}
+export const EXTERNAL_INVOKE_MAX_RETRIES = 3;
+export const EXTERNAL_INVOKE_BASE_DELAY_MS = 500;
+/** Per attempt. A timed-out attempt is retried like a network error. */
+export const EXTERNAL_INVOKE_TIMEOUT_MS = 30_000;
+/**
+ * POST to a remote resource, retrying network errors, 429s, and 5xx responses up to
+ * `EXTERNAL_INVOKE_MAX_RETRIES` times with exponential backoff (500ms, 1s, 2s).
+ * Other 4xx responses are returned immediately since retrying won't change them.
+ * Throws the last network error if every attempt fails to connect.
+ */
+async function fetchWithRetry(url, init) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            const response = await fetch(url, { ...init(), signal: AbortSignal.timeout(EXTERNAL_INVOKE_TIMEOUT_MS) });
+            if (response.status !== 429 && response.status < 500) {
+                return response;
+            }
+            if (attempt >= EXTERNAL_INVOKE_MAX_RETRIES) {
+                return response;
+            }
+        }
+        catch (error) {
+            if (attempt >= EXTERNAL_INVOKE_MAX_RETRIES) {
+                throw error;
+            }
+        }
+        await new Promise(resolve => setTimeout(resolve, EXTERNAL_INVOKE_BASE_DELAY_MS * 2 ** attempt));
+    }
 }
 export class CombinationResourceInvoker {
     resourceRepository;
     costLimitLamports;
     publicKey;
     privateKey;
-    constructor(resourceRepository, costLimitLamports, publicKey, privateKey) {
+    grantService;
+    /** Without a `grantService`, calls to restricted remote functions fail. */
+    constructor(resourceRepository, costLimitLamports, publicKey, privateKey, grantService) {
         this.resourceRepository = resourceRepository;
         this.costLimitLamports = costLimitLamports;
         this.publicKey = publicKey;
         this.privateKey = privateKey;
+        this.grantService = grantService;
     }
     /**
      * Invoke a function on a resource.
      * If the resource has a baseUrl, it will be invoked as a remote function.
+     * If the function is restricted, it attaches an authorization from a held grant.
      * If the resource has a paymentManifest, it will create a payment voucher and pass it to the resource.
      * Otherwise, it will be invoked as a local function.
      *
@@ -46,24 +86,36 @@ export class CombinationResourceInvoker {
             if (!resourceFunction) {
                 throw new Error(`Function ${functionName} not found in resource ${resource.name}`);
             }
+            const target = { resourcePath: resource.path, resourceName: resource.name, functionName, parameters };
+            // Checked before the voucher, so a call this node can't make never signs one.
+            const chain = resourceFunction.restricted ? await this.grantService?.chainFor(url, target) : undefined;
+            if (resourceFunction.restricted && !chain) {
+                return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: it requires a grant from ${url}, and this node holds none that covers the call` } };
+            }
             let paymentVoucher;
             if (resourceFunction.paymentManifest) {
                 console.log(`Resource function ${resource.name}.${functionName} has a payment manifest, creating payment voucher...`);
                 if (resourceFunction.paymentManifest.costLamports > this.costLimitLamports) {
                     throw new Error(`Function ${functionName} cost ${resourceFunction.paymentManifest.costLamports} lamports, which exceeds the cost limit of ${this.costLimitLamports} lamports`);
                 }
-                paymentVoucher = this.createPaymentVoucher(resourceFunction.paymentManifest.recipientAddress, resourceFunction.paymentManifest.costLamports, resource.path, resource.name, parameters);
+                paymentVoucher = this.createPaymentVoucher(resourceFunction.paymentManifest.recipientAddress, resourceFunction.paymentManifest.costLamports, resource.path, resource.name, functionName, parameters);
                 requestBody.paymentVoucher = paymentVoucher;
             }
-            const result = await fetch(`${url}/v1/run/resource`, {
+            // The voucher is created once and reused on every attempt, so the operator's
+            // requestId/invocationId check prevents a retried call from being settled twice.
+            // The authorization is signed per attempt, since the provider refuses a reused nonce.
+            const result = await fetchWithRetry(`${url}/v1/run/resource`, () => ({
                 method: 'POST',
-                body: JSON.stringify(requestBody),
+                body: JSON.stringify(chain && this.grantService ? { ...requestBody, authorization: this.grantService.authorize(chain, target) } : requestBody),
                 headers: {
                     'Content-Type': 'application/json',
                 },
-            });
+            }));
             if (!result.ok) {
-                return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: ${result.statusText}` } };
+                // The provider's JSON error is more useful than the status text, which can be empty.
+                const detail = await result.json().then((body) => body?.error, () => undefined);
+                const reason = typeof detail === 'string' ? detail : `${result.status} ${result.statusText}`.trim();
+                return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: ${reason}` } };
             }
             const data = await result.json();
             return { value: data.value, error: data.error };
@@ -77,12 +129,13 @@ export class CombinationResourceInvoker {
             return { value: result, error: null };
         }
     }
-    createPaymentVoucher(recipientAddress, amount, resourcePath, resourceName, parameters) {
+    createPaymentVoucher(recipientAddress, amount, resourcePath, resourceName, functionName, parameters) {
         const requestId = crypto.randomUUID();
         const invocationId = crypto.randomUUID();
         // Expire in 2 minutes
         const expiresAt = new Date(Date.now() + 1000 * 60 * 2).toISOString();
-        const signature = signData(paymentVoucherPayload({ requestId, invocationId, amount, recipientAddress, expiresAt, publicKey: this.publicKey }, resourcePath, resourceName, parameters), this.privateKey);
-        return { requestId, invocationId, amount, recipientAddress, signature, expiresAt, publicKey: this.publicKey };
+        const hash = invocationHash(resourcePath, resourceName, functionName, parameters);
+        const signature = signData(paymentVoucherPayload({ requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash: hash, publicKey: this.publicKey }), this.privateKey);
+        return { requestId, invocationId, amount, recipientAddress, signature, expiresAt, invocationHash: hash, publicKey: this.publicKey };
     }
 }

package/dist/resource/repository.d.ts

@@ -1,35 +1,82 @@
 import { Resource, ResourceFunction, ResourceFunctionParameter } from "requestscript";
 import { Database } from "sqlite";
-import type { Peer } from "../peer/repository.js";
+import type { StoredPeer } from "../peer/repository.js";
 export interface StellariumResourceFunctionPaymentManifest {
     id?: number;
     costLamports: number;
     recipientAddress: string;
 }
+export interface StellariumResourceFunctionParameter extends ResourceFunctionParameter {
+    description?: string;
+}
 export interface StellariumResourceFunction extends ResourceFunction {
     id?: number;
+    description?: string;
+    parameters: StellariumResourceFunctionParameter[];
     paymentManifest?: StellariumResourceFunctionPaymentManifest;
+    /** Callers need a grant from the hosting node. Announced to peers so callers can tell. */
+    restricted?: boolean;
 }
 export interface StellariumResource extends Resource {
     id: number;
     baseUrl: string;
+    /** A URL where callers can learn more about the resource. */
+    website?: string;
+    description?: string;
     functions: StellariumResourceFunction[];
 }
+/**
+ * The object a node signs to broadcast its resources. Key order is part of the signed bytes.
+ * Functions' `exec` implementations are dropped by JSON serialization on both ends.
+ */
+export declare function resourceAnnouncementPayload(resources: StellariumResource[], expiry: string): {
+    resources: StellariumResource[];
+    expiry: string;
+};
+export type SaveAllResult = {
+    ok: true;
+    rejected: string[];
+} | {
+    ok: false;
+};
 export declare class ResourceRepository {
     private readonly db;
     private resources;
-    constructor(db: Database, resources?: StellariumResource[]);
-    create(resource: StellariumResource): Promise<void>;
-    saveAll(resources: StellariumResource[], existingPeer: Peer, signature: string, expiry: string): Promise<boolean>;
-    getResourceByName(name: string): Promise<StellariumResource | undefined>;
-    getInternalResource(path: string, name: string): Promise<Resource | undefined>;
+    private readonly baseUrl;
+    private writes;
+    constructor(db: Database, resources?: StellariumResource[], baseUrl?: string);
+    private serialize;
+    private transaction;
+    private isInternal;
+    /**
+     * Saves a resource learned from the starting peer, if it isn't known yet. Resources hosted
+     * by this node and resources already known are left alone, so startup can run on every boot.
+     */
+    learn(resource: StellariumResource): Promise<void>;
+    /**
+     * Saves the resources a peer broadcast, after checking the peer signed them.
+     * A peer may only publish resources served from its own base URL, and may not replace a
+     * resource owned by another peer or hosted by this node. Those are returned in `rejected`.
+     * Accepted resources are replaced as a whole, so added or removed functions,
+     * parameters and payment manifests all take effect.
+     */
+    saveAll(resources: StellariumResource[], peer: StoredPeer, signature: string, expiry: string): Promise<SaveAllResult>;
+    private insert;
+    private insertFunctions;
+    private deleteFunctions;
+    getInternalResource(path: string, name: string): Promise<StellariumResource | undefined>;
     getResource(key: string): Promise<Resource | undefined>;
     getInternalResources(): Promise<StellariumResource[]>;
-    getExternalResources(): Promise<StellariumResource[]>;
+    /** Learned resources in insertion order. A negative `limit` means no limit. */
+    getExternalResources(offset?: number, limit?: number): Promise<StellariumResource[]>;
     getResourceFunction(resourcePath: string, resourceName: string, functionName: string): Promise<StellariumResourceFunction | undefined>;
     getResourceFunctions(resourceId: number): Promise<StellariumResourceFunction[]>;
-    getResourceParameters(resourceFunctionId: number): Promise<ResourceFunctionParameter[]>;
+    getResourceParameters(resourceFunctionId: number): Promise<StellariumResourceFunctionParameter[]>;
     getResourceFunctionPaymentManifest(resourceFunctionId: number): Promise<StellariumResourceFunctionPaymentManifest | undefined>;
-    getAllResources(): Promise<StellariumResource[]>;
+    /**
+     * One page of every resource this node knows: the ones it hosts first, then learned ones.
+     * Both are in a fixed order, so offsets stay stable as resources are learned.
+     */
+    getResources(offset: number, limit: number): Promise<StellariumResource[]>;
 }
 //# sourceMappingURL=repository.d.ts.map

package/dist/resource/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/resource/repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAElD,MAAM,WAAW,yCAAyC;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAChE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,eAAe,CAAC,EAAE,yCAAyC,CAAC;CAC/D;AAED,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,0BAA0B,EAAE,CAAC;CAC3C;AAED,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,EAAE;IAAY,OAAO,CAAC,SAAS;IAA5D,YAA6B,EAAE,EAAE,QAAQ,EAAU,SAAS,GAAE,kBAAkB,EAAO,EAAI;IAErF,MAAM,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmCxD;IAEK,OAAO,CAAC,SAAS,EAAE,kBAAkB,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsDtH;IAEK,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAE7E;IAEK,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAEnF;IAEK,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CA0C5D;IAEK,oBAAoB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAE1D;IAEK,oBAAoB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiB1D;IAEK,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,GAAG,SAAS,CAAC,CAmB3I;IAEK,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAUpF;IAEK,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAK5F;IAEK,kCAAkC,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,yCAAyC,GAAG,SAAS,CAAC,CAUnI;IAEK,eAAe,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CASrD;CACJ"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/resource/repository.ts"],"names":[],"mappings":"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"}

package/dist/resource/repository.js

@@ -1,68 +1,140 @@
-import { verifyData } from "../crypto/utils.js";
+import { isFreshExpiry, safeVerifyData } from "../crypto/utils.js";
+/**
+ * The object a node signs to broadcast its resources. Key order is part of the signed bytes.
+ * Functions' `exec` implementations are dropped by JSON serialization on both ends.
+ */
+export function resourceAnnouncementPayload(resources, expiry) {
+    return { resources, expiry };
+}
+/** Peers' resources aren't validated on receipt, so a description that isn't a string is stored as absent. */
+function optionalText(value) {
+    return typeof value === 'string' ? value : null;
+}
+/** Only http(s) URLs are kept, since clients may render a resource's website as a link. */
+function optionalWebsite(value) {
+    if (typeof value !== 'string' || !URL.canParse(value)) {
+        return null;
+    }
+    const { protocol } = new URL(value);
+    return protocol === 'http:' || protocol === 'https:' ? value : null;
+}
+const resourceKey = (resource) => `${resource.path}.${resource.name}`;
 export class ResourceRepository {
     db;
     resources;
-    constructor(db, resources = []) {
+    baseUrl;
+    // The connection is shared, so transactions are serialized to keep them from nesting.
+    writes = Promise.resolve();
+    constructor(db, resources = [], baseUrl = '') {
         this.db = db;
         this.resources = resources;
+        this.baseUrl = baseUrl;
+    }
+    serialize(work) {
+        const run = this.writes.then(work, work);
+        this.writes = run.catch(() => undefined);
+        return run;
+    }
+    transaction(work) {
+        return this.serialize(async () => {
+            await this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const result = await work();
+                await this.db.exec('COMMIT');
+                return result;
+            }
+            catch (error) {
+                await this.db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    isInternal(resource) {
+        return this.resources.some(r => r.path === resource.path && r.name === resource.name);
+    }
+    /**
+     * Saves a resource learned from the starting peer, if it isn't known yet. Resources hosted
+     * by this node and resources already known are left alone, so startup can run on every boot.
+     */
+    async learn(resource) {
+        if (this.isInternal(resource) || resource.baseUrl === this.baseUrl) {
+            return;
+        }
+        await this.transaction(async () => {
+            const existing = await this.db.get('SELECT id FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
+            if (!existing) {
+                await this.insert(resource, null);
+            }
+        });
+    }
+    /**
+     * Saves the resources a peer broadcast, after checking the peer signed them.
+     * A peer may only publish resources served from its own base URL, and may not replace a
+     * resource owned by another peer or hosted by this node. Those are returned in `rejected`.
+     * Accepted resources are replaced as a whole, so added or removed functions,
+     * parameters and payment manifests all take effect.
+     */
+    async saveAll(resources, peer, signature, expiry) {
+        if (!Array.isArray(resources) || !isFreshExpiry(expiry) || !safeVerifyData(resourceAnnouncementPayload(resources, expiry), peer.publicKey, signature)) {
+            return { ok: false };
+        }
+        const rejected = [];
+        await this.transaction(async () => {
+            for (const resource of resources) {
+                if (resource.baseUrl !== peer.baseUrl || this.isInternal(resource)) {
+                    rejected.push(resourceKey(resource));
+                    continue;
+                }
+                const existing = await this.db.get('SELECT * FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
+                if (!existing) {
+                    await this.insert(resource, peer.id);
+                    continue;
+                }
+                // Unowned rows came from the starting peer; the peer they point at may claim them.
+                const ownedByPeer = existing.peer_id === null ? existing.base_url === peer.baseUrl : existing.peer_id === peer.id;
+                if (!ownedByPeer) {
+                    rejected.push(resourceKey(resource));
+                    continue;
+                }
+                await this.deleteFunctions(existing.id);
+                await this.db.run('UPDATE resource SET base_url = ?, website = ?, description = ?, peer_id = ?, updated_at = ? WHERE id = ?', [resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peer.id, new Date().toISOString(), existing.id]);
+                await this.insertFunctions(existing.id, resource.functions);
+            }
+        });
+        return { ok: true, rejected };
     }
-    async create(resource) {
+    async insert(resource, peerId) {
         const createdAt = new Date().toISOString();
-        const result = await this.db.run('INSERT INTO resource (path, name, base_url, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [resource.path, resource.name, resource.baseUrl, createdAt, createdAt]);
-        if (!result.changes) {
+        const result = await this.db.run('INSERT INTO resource (path, name, base_url, website, description, peer_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [resource.path, resource.name, resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peerId, createdAt, createdAt]);
+        if (!result.changes || result.lastID === undefined) {
             throw new Error('Failed to create resource');
         }
-        const resourceId = result.lastID;
-        for (const fn of resource.functions) {
-            const functionResult = await this.db.run('INSERT INTO resource_function (resource_id, name, return_type, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [resourceId, fn.name, fn.returnType, createdAt, createdAt]);
+        await this.insertFunctions(result.lastID, resource.functions);
+    }
+    async insertFunctions(resourceId, functions) {
+        const createdAt = new Date().toISOString();
+        for (const fn of functions) {
+            const functionResult = await this.db.run('INSERT INTO resource_function (resource_id, name, return_type, description, restricted, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)', [resourceId, fn.name, fn.returnType, optionalText(fn.description), fn.restricted === true ? 1 : 0, createdAt, createdAt]);
             const functionId = functionResult.lastID;
             for (const parameter of fn.parameters) {
-                await this.db.run('INSERT INTO resource_function_parameter (resource_function_id, name, parameter_type, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [functionId, parameter.name, parameter.type, createdAt, createdAt]);
+                await this.db.run('INSERT INTO resource_function_parameter (resource_function_id, name, parameter_type, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)', [functionId, parameter.name, parameter.type, optionalText(parameter.description), createdAt, createdAt]);
             }
             if (fn.paymentManifest) {
                 await this.db.run('INSERT INTO resource_function_payment_manifest (resource_function_id, cost_lamports, recipient_address, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [functionId, fn.paymentManifest.costLamports, fn.paymentManifest.recipientAddress, createdAt, createdAt]);
             }
         }
     }
-    async saveAll(resources, existingPeer, signature, expiry) {
-        if (!verifyData({ resources, expiry }, existingPeer.publicKey, signature) || new Date(expiry) < new Date()) {
-            return false;
-        }
-        for (const resource of resources) {
-            const existingResource = await this.db.get('SELECT * FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
-            // TODO: A signature must accompany the resource to ensure the base url change is only made by the owner of the resource.
-            // This will avoid MITM attacks.
-            if (existingResource) {
-                await this.db.run('UPDATE resource SET base_url = ?, updated_at = ? WHERE path = ? AND name = ?', [resource.baseUrl, new Date().toISOString(), resource.path, resource.name]);
-                for (const fn of resource.functions) {
-                    const updatedAt = new Date().toISOString();
-                    await this.db.run('UPDATE resource_function SET return_type = ?, updated_at = ? WHERE resource_id = ? AND name = ?', [fn.returnType, updatedAt, existingResource.id, fn.name]);
-                    const existingFn = await this.db.get('SELECT id FROM resource_function WHERE resource_id = ? AND name = ?', [existingResource.id, fn.name]);
-                    if (!existingFn) {
-                        continue;
-                    }
-                    for (const parameter of fn.parameters) {
-                        await this.db.run('UPDATE resource_function_parameter SET parameter_type = ? WHERE resource_function_id = ? AND name = ?', [parameter.type, existingFn.id, parameter.name]);
-                    }
-                    if (fn.paymentManifest) {
-                        await this.db.run('UPDATE resource_function_payment_manifest SET cost_lamports = ?, recipient_address = ?, updated_at = ? WHERE resource_function_id = ?', [fn.paymentManifest.costLamports, fn.paymentManifest.recipientAddress, updatedAt, existingFn.id]);
-                    }
-                }
-            }
-            else {
-                await this.create(resource);
-            }
-        }
-        return true;
-    }
-    async getResourceByName(name) {
-        return this.resources.find(r => r.name === name);
+    async deleteFunctions(resourceId) {
+        const functionIds = 'SELECT id FROM resource_function WHERE resource_id = ?';
+        await this.db.run(`DELETE FROM resource_function_payment_manifest WHERE resource_function_id IN (${functionIds})`, [resourceId]);
+        await this.db.run(`DELETE FROM resource_function_parameter WHERE resource_function_id IN (${functionIds})`, [resourceId]);
+        await this.db.run('DELETE FROM resource_function WHERE resource_id = ?', [resourceId]);
     }
     async getInternalResource(path, name) {
         return this.resources.find(r => r.path === path && r.name === name);
     }
     async getResource(key) {
-        const resource = this.resources.find(r => `${r.path}.${r.name}` === key);
+        const resource = this.resources.find(r => resourceKey(r) === key);
         if (resource) {
             return resource;
         }
@@ -74,38 +146,29 @@ export class ResourceRepository {
         if (!result) {
             return undefined;
         }
-        const resourceFunctions = await this.db.all('SELECT * FROM resource_function WHERE resource_id = ?', [result.id]);
         return {
             path: result.path,
             name: result.name,
-            functions: await Promise.all(resourceFunctions.map(async (f) => ({
-                name: f.name,
-                returnType: f.return_type,
-                parameters: await this.getResourceParameters(f.id),
-                // The ExternalResourceInvoker will handle the execution of the function
-                exec: async () => {
-                    return void 0;
-                }
-            }))),
+            // The CombinationResourceInvoker forwards calls on these functions to `metadata.baseUrl`.
+            functions: await this.getResourceFunctions(result.id),
             metadata: {
                 baseUrl: result.base_url,
-                paymentManifest: await this.getResourceFunctionPaymentManifest(result.id),
             }
         };
     }
     async getInternalResources() {
-        return this.resources.map(r => ({ ...r, baseUrl: process.env.BASE_URL }));
+        return this.resources.map(r => ({ ...r, baseUrl: this.baseUrl }));
     }
-    async getExternalResources() {
-        const results = await this.db.all('SELECT * FROM resource');
-        if (!results) {
-            return [];
-        }
+    /** Learned resources in insertion order. A negative `limit` means no limit. */
+    async getExternalResources(offset = 0, limit = -1) {
+        const results = await this.db.all('SELECT * FROM resource ORDER BY id LIMIT ? OFFSET ?', [limit, offset]);
         return Promise.all(results.map(async (r) => ({
             id: r.id,
             path: r.path,
             name: r.name,
             baseUrl: r.base_url,
+            website: r.website ?? undefined,
+            description: r.description ?? undefined,
             metadata: { baseUrl: r.base_url },
             functions: await this.getResourceFunctions(r.id),
         })));
@@ -123,9 +186,11 @@ export class ResourceRepository {
             id: fn.id,
             name: fn.name,
             returnType: fn.return_type,
+            description: fn.description ?? undefined,
             parameters: await this.getResourceParameters(fn.id),
             exec: async () => undefined,
             paymentManifest: await this.getResourceFunctionPaymentManifest(fn.id),
+            restricted: fn.restricted === 1 || undefined,
         };
     }
     async getResourceFunctions(resourceId) {
@@ -134,15 +199,18 @@ export class ResourceRepository {
             id: f.id,
             name: f.name,
             returnType: f.return_type,
+            description: f.description ?? undefined,
             parameters: await this.getResourceParameters(f.id),
             exec: async () => undefined,
             paymentManifest: await this.getResourceFunctionPaymentManifest(f.id),
+            restricted: f.restricted === 1 || undefined,
         })));
     }
     async getResourceParameters(resourceFunctionId) {
-        return (await this.db.all('SELECT * FROM resource_function_parameter WHERE resource_function_id = ?', [resourceFunctionId])).map(p => ({
+        return (await this.db.all('SELECT * FROM resource_function_parameter WHERE resource_function_id = ? ORDER BY id', [resourceFunctionId])).map(p => ({
             name: p.name,
             type: p.parameter_type,
+            description: p.description ?? undefined,
         }));
     }
     async getResourceFunctionPaymentManifest(resourceFunctionId) {
@@ -156,13 +224,17 @@ export class ResourceRepository {
             recipientAddress: result.recipient_address,
         };
     }
-    async getAllResources() {
-        const externalResources = await this.getExternalResources();
-        let resources = [];
-        for (const resource of Object.values(this.resources)) {
-            resources.push({ ...resource, baseUrl: process.env.BASE_URL });
+    /**
+     * One page of every resource this node knows: the ones it hosts first, then learned ones.
+     * Both are in a fixed order, so offsets stay stable as resources are learned.
+     */
+    async getResources(offset, limit) {
+        const internal = (await this.getInternalResources()).slice(offset, offset + limit);
+        const remaining = limit - internal.length;
+        if (remaining <= 0) {
+            return internal;
         }
-        resources.push(...externalResources);
-        return resources;
+        const externalOffset = Math.max(0, offset - this.resources.length);
+        return [...internal, ...await this.getExternalResources(externalOffset, remaining)];
     }
 }

package/dist/routes.d.ts

@@ -1,8 +1,16 @@
 import type { FastifyPluginAsync } from 'fastify';
 import type { Service } from './service.js';
+export interface RateLimitConfig {
+    max: number;
+    /** Milliseconds, or a string such as '1 minute'. */
+    timeWindow: number | string;
+}
 interface RouteOptions {
     service: Service;
+    rateLimit?: RateLimitConfig;
 }
+export declare const DEFAULT_PAGE_SIZE = 100;
+export declare const MAX_PAGE_SIZE = 500;
 /**
  * Encapsulates the routes
  * @param fastify Encapsulated Fastify Instance

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAKlD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,UAAU,YAAY;IAClB,OAAO,EAAE,OAAO,CAAC;CACpB;AA+BD;;;;GAIG;AACH,QAAA,MAAM,MAAM,EAAE,kBAAkB,CAAC,YAAY,CAmJ5C,CAAC;eAGa,MAAM"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAKhF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED,UAAU,YAAY;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAiDD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,aAAa,MAAM,CAAC;AAsHjC;;;;GAIG;AACH,QAAA,MAAM,MAAM,EAAE,kBAAkB,CAAC,YAAY,CAqS5C,CAAC;eAGa,MAAM"}