stellarium-ts 0.11.0 → 0.13.0

package/dist/routes.js

@@ -1,12 +1,148 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import rateLimit from '@fastify/rate-limit';
 import { interpretParsed, parseScript } from 'requestscript';
-import { paymentVoucherPayload } from './resource/invoker.js';
-import { verifyData } from './crypto/utils.js';
+import { invocationHash, paymentVoucherPayload } from './resource/invoker.js';
+import { safeVerifyData } from './crypto/utils.js';
+import { InvalidPublicKeyError } from './grant/service.js';
+// Body schemas check only the shape the handlers rely on. Signed payloads (resources) are
+// left unvalidated inside, since coercing or stripping them would change the signed bytes.
+const nonEmptyString = { type: 'string', minLength: 1 };
+const peerRequestSchema = {
+    type: 'object',
+    required: ['baseUrl', 'name', 'publicKey', 'signature', 'expiry'],
+    properties: { baseUrl: nonEmptyString, name: nonEmptyString, publicKey: nonEmptyString, signature: nonEmptyString, expiry: nonEmptyString },
+};
+const resourceRequestSchema = {
+    type: 'object',
+    required: ['publicKey', 'signature', 'expiry', 'resources'],
+    properties: { publicKey: nonEmptyString, signature: nonEmptyString, expiry: nonEmptyString, resources: { type: 'array' } },
+};
+export const DEFAULT_PAGE_SIZE = 100;
+export const MAX_PAGE_SIZE = 500;
+const pageQuerySchema = {
+    type: 'object',
+    properties: {
+        offset: { type: 'integer', minimum: 0, default: 0 },
+        limit: { type: 'integer', minimum: 1, maximum: MAX_PAGE_SIZE, default: DEFAULT_PAGE_SIZE },
+    },
+};
+const revokeQuerySchema = {
+    type: 'object',
+    properties: {
+        issuer: { type: 'string', minLength: 1 },
+    },
+};
+/**
+ * Fetches one extra item to tell whether another page follows. `nextOffset` is null on the last page.
+ */
+async function getPage(query, fetchPage) {
+    const { offset, limit } = query;
+    const items = await fetchPage(offset, limit + 1);
+    return {
+        items: items.slice(0, limit),
+        nextOffset: items.length > limit ? offset + limit : null,
+    };
+}
+const runRequestSchema = {
+    type: 'object',
+    required: ['source'],
+    properties: { source: { type: 'string' } },
+};
+const resourceRunRequestSchema = {
+    type: 'object',
+    required: ['resourcePath', 'resourceName', 'functionName', 'parameters'],
+    properties: {
+        resourcePath: { type: 'string' },
+        resourceName: { type: 'string' },
+        functionName: { type: 'string' },
+        parameters: {
+            type: 'array',
+            items: { type: 'object', required: ['name'], properties: { name: { type: 'string' } } },
+        },
+        paymentVoucher: {
+            type: 'object',
+            required: ['requestId', 'invocationId', 'amount', 'recipientAddress', 'signature', 'expiresAt', 'invocationHash', 'publicKey'],
+            properties: {
+                requestId: { type: 'string' },
+                invocationId: { type: 'string' },
+                amount: { type: 'integer' },
+                recipientAddress: { type: 'string' },
+                signature: { type: 'string' },
+                expiresAt: { type: 'string' },
+                invocationHash: { type: 'string' },
+                publicKey: { type: 'string' },
+            },
+        },
+        // Shape only: the grants inside are signed, so coercing them would change the signed bytes.
+        authorization: { type: 'object' },
+    },
+};
+const grantRenewalRequestSchema = {
+    type: 'object',
+    required: ['grantId', 'publicKey', 'nonce', 'expiresAt', 'signature'],
+    properties: { grantId: nonEmptyString, publicKey: nonEmptyString, nonce: nonEmptyString, expiresAt: nonEmptyString, signature: nonEmptyString },
+};
+// Capabilities and details are signed, so only their outer types are checked here.
+const grantRequestSchema = {
+    type: 'object',
+    required: ['publicKey', 'capabilities', 'nonce', 'expiresAt', 'signature'],
+    properties: {
+        publicKey: nonEmptyString,
+        capabilities: { type: 'array', minItems: 1 },
+        details: { type: ['object', 'null'] },
+        nonce: nonEmptyString,
+        expiresAt: nonEmptyString,
+        signature: nonEmptyString,
+    },
+};
+/** Constant-time comparison. Hashing first gives equal-length buffers for timingSafeEqual. */
+function secretsEqual(a, b) {
+    const digest = (value) => createHash('sha256').update(value).digest();
+    return timingSafeEqual(digest(a), digest(b));
+}
+/**
+ * A voucher is valid when it is bound to this exact call, signed by its public key, unexpired,
+ * and pays at least the function's cost to the function's recipient.
+ */
+function isValidPaymentVoucher(voucher, manifest, request) {
+    const expectedHash = invocationHash(request.resourcePath, request.resourceName, request.functionName, request.parameters);
+    if (voucher.invocationHash !== expectedHash) {
+        return false;
+    }
+    if (voucher.amount < manifest.costLamports) {
+        return false;
+    }
+    if (voucher.recipientAddress !== manifest.recipientAddress) {
+        return false;
+    }
+    const expiresAt = Date.parse(voucher.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+        return false;
+    }
+    return safeVerifyData(paymentVoucherPayload(voucher), voucher.publicKey, voucher.signature);
+}
 /**
  * Encapsulates the routes
  * @param fastify Encapsulated Fastify Instance
  * @param options plugin options, refer to https://fastify.dev/docs/latest/Reference/Plugins/#plugin-options
  */
 const routes = async (fastify, options) => {
+    // Rate limiting is opt-in per route via `config.rateLimit`.
+    await fastify.register(rateLimit, { global: false });
+    /** Requires `Authorization: Bearer <API_KEY>`. Used by the routes only this node's operator may call. */
+    const requireApiKey = async (request, reply) => {
+        // Check that the API Key matches the configured key
+        const authorizationHeader = request.headers['authorization'];
+        if (!authorizationHeader) {
+            return reply.status(401).send({ error: 'Authorization header is required' });
+        }
+        const apiKey = authorizationHeader.split(' ')[1];
+        // An unset API key must not match a header with no token.
+        const expectedApiKey = options.service.config.apiKey;
+        if (!expectedApiKey || !apiKey || !secretsEqual(apiKey, expectedApiKey)) {
+            return reply.status(401).send({ error: 'Invalid API Key' });
+        }
+    };
     // Start Meta Routes
     fastify.get('/', async (request, reply) => {
         return {
@@ -14,27 +150,28 @@ const routes = async (fastify, options) => {
         };
     });
     fastify.get('/self', async (request, reply) => {
-        return {
-            baseUrl: process.env.BASE_URL,
-            publicKey: process.env.SIGNING_PUBLIC_KEY,
-            name: process.env.BASE_URL,
-        };
+        const { baseUrl, publicKey } = options.service.config;
+        return { baseUrl, publicKey, name: baseUrl };
     });
-    fastify.get('/peers', async (request, reply) => {
-        const peers = await options.service.peerRepository.getPeerList();
-        return { peers };
+    fastify.get('/peers', { schema: { querystring: pageQuerySchema } }, async (request, reply) => {
+        const { items: peers, nextOffset } = await getPage(request.query, (offset, limit) => options.service.peerRepository.getPeers(offset, limit));
+        return { peers, nextOffset };
     });
-    fastify.put('/peers', async (request, reply) => {
-        const peer = request.body;
-        await options.service.peerRepository.createIfNotExists(peer, peer.signature, peer.expiry);
+    fastify.put('/peers', { schema: { body: peerRequestSchema } }, async (request, reply) => {
+        const { baseUrl, name, publicKey, signature, expiry } = request.body;
+        const result = await options.service.peerRepository.announce({ baseUrl, name, publicKey }, signature, expiry);
+        if (!result.ok) {
+            return result.error === 'conflict'
+                ? reply.status(409).send({ error: 'Base URL or name belongs to another peer' })
+                : reply.status(400).send({ error: 'Invalid signature' });
+        }
         return { success: true };
     });
     /**
-     * Returns the list of resources that are available on the server.
-     * Does not return resources that are external to the server.
+     * Returns one page of the resources hosted on this node, followed by the resources it learned from peers.
      */
-    fastify.get('/resources', async (request, reply) => {
-        const resources = await options.service.resourceRepository.getAllResources();
+    fastify.get('/resources', { schema: { querystring: pageQuerySchema } }, async (request, reply) => {
+        const { items: resources, nextOffset } = await getPage(request.query, (offset, limit) => options.service.resourceRepository.getResources(offset, limit));
         return {
             resources: resources.map((resource) => ({
                 path: resource.path,
@@ -47,42 +184,44 @@ const routes = async (fastify, options) => {
                         costLamports: fn.paymentManifest.costLamports,
                         recipientAddress: fn.paymentManifest.recipientAddress,
                     }) : undefined,
+                    restricted: fn.restricted || undefined,
                 })),
                 baseUrl: resource.baseUrl,
             })),
+            nextOffset,
         };
     });
-    fastify.put('/all-resources', async (request, reply) => {
+    fastify.put('/all-resources', { schema: { body: resourceRequestSchema } }, async (request, reply) => {
         const resourceRequest = request.body;
         const resources = resourceRequest.resources;
         const existingPeer = await options.service.peerRepository.getPeerByPublicKey(resourceRequest.publicKey);
         if (!existingPeer) {
             return reply.status(400).send({ error: 'Peer not found' });
         }
-        const success = await options.service.resourceRepository.saveAll(resources, existingPeer, resourceRequest.signature, resourceRequest.expiry);
-        if (!success) {
+        const result = await options.service.resourceRepository.saveAll(resources, existingPeer, resourceRequest.signature, resourceRequest.expiry);
+        if (!result.ok) {
             return reply.status(400).send({ error: 'Invalid signature' });
         }
-        return { success: true };
+        // Resources this peer may not publish (not served from its base URL, or owned elsewhere).
+        return { success: true, rejected: result.rejected };
     });
     // End Meta Routes
     // Start Run Routes
-    fastify.post('/run', async (request, reply) => {
+    // Authenticate before body validation, so unauthenticated callers learn nothing about the schema.
+    fastify.post('/run', { schema: { body: runRequestSchema }, preValidation: requireApiKey }, async (request, reply) => {
         const runRequest = request.body;
-        // Check that the API Key matches the env variable
-        const authorizationHeader = request.headers['authorization'];
-        if (!authorizationHeader) {
-            return reply.status(401).send({ error: 'Authorization header is required' });
+        let script;
+        try {
+            script = parseScript(runRequest.source);
         }
-        const apiKey = authorizationHeader.split(' ')[1];
-        if (apiKey !== process.env.API_KEY) {
-            return reply.status(401).send({ error: 'Invalid API Key' });
+        catch (error) {
+            // A script that doesn't parse is the caller's mistake, not a server failure.
+            return reply.status(400).send({ error: 'Invalid script', details: error instanceof Error ? error.message : undefined });
+        }
+        if (script.declaration.kind !== 'request') {
+            return reply.status(400).send({ error: 'Invalid script' });
         }
         try {
-            const script = parseScript(runRequest.source);
-            if (script.declaration.kind !== 'request') {
-                return reply.status(400).send({ error: 'Invalid script' });
-            }
             const result = await interpretParsed(script, {
                 resourceResolver: options.service.resourceResolver,
                 resourceInvoker: options.service.resourceInvoker
@@ -94,34 +233,149 @@ const routes = async (fastify, options) => {
             reply.status(500).send({ error: 'Internal server error' });
         }
     });
-    fastify.post('/run/resource', async (request, reply) => {
+    fastify.post('/run/resource', {
+        schema: { body: resourceRunRequestSchema },
+        config: { rateLimit: options.rateLimit ?? { max: 100, timeWindow: '1 minute' } },
+    }, async (request, reply) => {
         const resourceRequest = request.body;
         const paymentVoucher = resourceRequest.paymentVoucher;
-        if (paymentVoucher) {
-            const isValid = verifyData(paymentVoucherPayload(paymentVoucher, resourceRequest.resourcePath, resourceRequest.resourceName, resourceRequest.parameters), paymentVoucher.publicKey, paymentVoucher.signature);
-            if (!isValid) {
-                return reply.status(400).send({ error: 'Invalid payment voucher' });
-            }
-        }
         const resource = await options.service.resourceRepository.getInternalResource(resourceRequest.resourcePath, resourceRequest.resourceName);
         if (!resource) {
             return reply.status(400).send({ error: 'Resource not found' });
         }
+        const resourceFunction = resource.functions.find(fn => fn.name === resourceRequest.functionName);
+        if (!resourceFunction) {
+            return reply.status(400).send({ error: 'Function not found' });
+        }
+        // Grant constraints and the function both read parameters by name, so each name must be
+        // declared and appear once. Otherwise a duplicate or extra parameter could pass a
+        // constraint check with one value and reach the function with another.
+        const declared = new Set(resourceFunction.parameters.map(parameter => parameter.name));
+        const names = resourceRequest.parameters.map(parameter => parameter.name);
+        if (new Set(names).size !== names.length || !names.every(name => declared.has(name))) {
+            return reply.status(400).send({ error: 'Parameters must be declared by the function and appear once each' });
+        }
+        // A restricted function is never run without a grant from this node. Checked before the
+        // voucher, so an unauthorized caller never gets near settlement.
+        if (resourceFunction.restricted) {
+            // Tells a caller without a usable grant where it can ask for one.
+            const grantEndpoint = options.service.grantService.acceptsRequests ? `${options.service.config.baseUrl}/v1/grants/request` : undefined;
+            if (!resourceRequest.authorization) {
+                return reply.status(403).send({ error: 'Authorization is required', grantEndpoint });
+            }
+            if (!await options.service.grantService.verifyInvocation(resourceRequest.authorization, resourceRequest)) {
+                return reply.status(403).send({ error: 'Invalid authorization', grantEndpoint });
+            }
+        }
+        // Payment manifests are per function. A paid function is never run without a valid voucher.
+        const paymentManifest = resourceFunction.paymentManifest;
+        if (paymentManifest) {
+            if (!paymentVoucher) {
+                return reply.status(402).send({ error: 'Payment voucher is required' });
+            }
+            if (!isValidPaymentVoucher(paymentVoucher, paymentManifest, resourceRequest)) {
+                return reply.status(400).send({ error: 'Invalid payment voucher' });
+            }
+            if (await options.service.grantService.isBlocked(paymentVoucher.publicKey)) {
+                return reply.status(403).send({ error: 'Caller is blocked' });
+            }
+        }
         const result = await options.service.resourceInvoker.invoke(resource, resourceRequest.functionName, resourceRequest.parameters);
-        // A voucher is optional. Settlement runs only after a successful invoke. Run this on a separate thread to avoid blocking the main thread.
-        if (paymentVoucher) {
+        // Settle only verified vouchers, and only after a successful invoke. A voucher sent to a free function is ignored.
+        // Run this on a separate thread to avoid blocking the main thread.
+        if (paymentManifest && paymentVoucher && !result.error) {
             setTimeout(async () => {
-                await options.service.operatorClient.settlePayment({
-                    voucher: paymentVoucher,
-                    resourcePath: resourceRequest.resourcePath,
-                    resourceName: resourceRequest.resourceName,
-                    parameters: resourceRequest.parameters,
-                });
+                // Nothing awaits this callback, so an uncaught error here would be an unhandled rejection.
+                try {
+                    await options.service.operatorClient.settlePayment({ voucher: paymentVoucher });
+                }
+                catch (error) {
+                    fastify.log.error(error, 'Failed to settle payment');
+                }
             }, 0);
         }
-        return { returnValue: result };
+        return result;
     });
     // End Run Routes
+    // Start Grant Routes
+    /** Issues a root grant to the request's signer, if the node's approval hook allows it. */
+    fastify.post('/grants/request', {
+        schema: { body: grantRequestSchema },
+        config: { rateLimit: options.rateLimit ?? { max: 100, timeWindow: '1 minute' } },
+    }, async (request, reply) => {
+        if (!options.service.grantService.acceptsRequests) {
+            return reply.status(403).send({ error: 'This node does not issue grants on request' });
+        }
+        let grants;
+        try {
+            grants = await options.service.grantService.handleRequest(request.body);
+        }
+        catch (error) {
+            // An approval hook that throws or returns an invalid approval is this node's fault, not the requester's.
+            fastify.log.error(error, 'Failed to decide grant request');
+            return reply.status(500).send({ error: 'Internal server error' });
+        }
+        if (!grants) {
+            return reply.status(403).send({ error: 'Grant request refused' });
+        }
+        return { grants };
+    });
+    /** Re-issues a grant this node issued to the grant's audience, with a new expiry. */
+    fastify.post('/grants/renew', {
+        schema: { body: grantRenewalRequestSchema },
+        config: { rateLimit: options.rateLimit ?? { max: 100, timeWindow: '1 minute' } },
+    }, async (request, reply) => {
+        const grants = await options.service.grantService.renew(request.body);
+        if (!grants) {
+            return reply.status(403).send({ error: 'Grant renewal refused' });
+        }
+        return { grants };
+    });
+    // End Grant Routes
+    // Start Admin Routes
+    // Authenticated before validation, like /run, so unauthenticated callers learn nothing about the schema.
+    /**
+     * Revokes a grant: this node refuses it in any chain, with everything delegated from it, and
+     * stops renewing it. Without `?issuer=`, the grant is one this node issued. With it, the grant
+     * may be one delegated further down a chain, so it can be cut off too.
+     */
+    fastify.put('/admin/revoked-grants/:grantId', { preValidation: requireApiKey, schema: { querystring: revokeQuerySchema } }, async (request) => {
+        const { grantId } = request.params;
+        const { issuer } = request.query;
+        await options.service.grantService.revoke(issuer === undefined ? grantId : { issuer, id: grantId });
+        return { success: true };
+    });
+    fastify.get('/admin/blocked-callers', { preValidation: requireApiKey, schema: { querystring: pageQuerySchema } }, async (request) => {
+        const { items: callers, nextOffset } = await getPage(request.query, (offset, limit) => options.service.grantService.getBlocked(offset, limit));
+        return { callers, nextOffset };
+    });
+    /** Blocks a caller key, with an optional `{ "reason" }` body. Unrestricted free functions stay open to it, since their callers are anonymous. */
+    fastify.put('/admin/blocked-callers/:publicKey', { preValidation: requireApiKey }, async (request, reply) => {
+        const { publicKey } = request.params;
+        // The body is optional, so it is checked here rather than by a schema that would require one.
+        const reason = request.body?.reason;
+        if (reason !== undefined && typeof reason !== 'string') {
+            return reply.status(400).send({ error: 'reason must be a string' });
+        }
+        try {
+            await options.service.grantService.block(publicKey, reason);
+        }
+        catch (error) {
+            if (error instanceof InvalidPublicKeyError) {
+                return reply.status(400).send({ error: error.message });
+            }
+            throw error;
+        }
+        return { success: true };
+    });
+    fastify.delete('/admin/blocked-callers/:publicKey', { preValidation: requireApiKey }, async (request, reply) => {
+        const { publicKey } = request.params;
+        if (!await options.service.grantService.unblock(publicKey)) {
+            return reply.status(404).send({ error: 'Caller is not blocked' });
+        }
+        return { success: true };
+    });
+    // End Admin Routes
 };
 // ESM
 export default routes;

package/dist/server.d.ts

@@ -1,14 +1,76 @@
 import 'dotenv/config';
 import { FastifyInstance } from 'fastify';
+import type { Capability, Grant } from './grant/grant.js';
+import type { GrantKey } from './grant/repository.js';
+import type { ApproveGrant, GrantOptions } from './grant/service.js';
 import { StellariumResource } from './resource/repository.js';
+import { RateLimitConfig } from './routes.js';
+import { type NodeConfig } from './service.js';
+export declare const DEFAULT_COST_LIMIT_LAMPORTS = 10000;
+export declare const DEFAULT_GRANT_REFRESH_INTERVAL_MS: number;
 export interface StellariumNodeOptions {
     port?: number;
     host?: string;
     startingPeer?: string;
+    /** Per-IP rate limit for `POST /v1/run/resource`. Defaults to 100 requests per minute. */
+    rateLimit?: RateLimitConfig;
+    /** URL peers use to reach this node. Defaults to `BASE_URL`. */
+    baseUrl?: string;
+    /** Defaults to `SIGNING_PUBLIC_KEY`. */
+    publicKey?: string;
+    /** Defaults to `SIGNING_PRIVATE_KEY`. */
+    privateKey?: string;
+    /** Bearer token for `POST /v1/run`. Defaults to `API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `OPERATOR_URL`. */
+    operatorUrl?: string;
+    /** Most this node pays for one remote call. Defaults to `COST_LIMIT_LAMPORTS`, then 10,000. */
+    costLimitLamports?: number;
+    /** SQLite file. Defaults to `./requestscript.db`; use ':memory:' for tests. */
+    databasePath?: string;
+    /**
+     * Grant chains addressed to this node, stored at start. Each is root first. A stored renewal
+     * of the same grant is kept, and an expired chain is skipped with a warning.
+     */
+    grants?: Grant[][];
+    /** How often held grants past half their lifetime are renewed. Defaults to 5 minutes. */
+    grantRefreshIntervalMs?: number;
+    /**
+     * Decides callers' requests for grants on this node's resources (`POST /v1/grants/request`).
+     * Without it, callers can only get grants from `issueGrant`.
+     */
+    approveGrant?: ApproveGrant;
 }
+export declare function resolveConfig(options: StellariumNodeOptions, resources?: StellariumResource[]): NodeConfig;
 export declare class StellariumNode {
     private resources;
+    private service?;
     register(resource: StellariumResource): Promise<void>;
+    /**
+     * Listens, then bootstraps from `startingPeer` if one is given.
+     * Rejects if the server can't listen or bootstrapping fails.
+     */
     start(fastify: FastifyInstance, options: StellariumNodeOptions): Promise<void>;
+    /** Issues a root grant for this node's resources. Hand the returned chain to the audience. */
+    issueGrant(audience: string, capabilities: Capability[], options: GrantOptions): Promise<Grant[]>;
+    /**
+     * Narrows a grant this node holds for another audience. Hand the returned chain to the audience.
+     * Name the held grant by its id, or by its issuer and id when two issuers used the same id.
+     */
+    delegateGrant(heldGrant: string | GrantKey, audience: string, capabilities: Capability[], options: GrantOptions): Promise<Grant[]>;
+    /** Asks another node for a grant on its resources, and stores it. Throws if refused. */
+    requestGrant(providerBaseUrl: string, capabilities: Capability[], details?: Record<string, unknown>): Promise<Grant[]>;
+    /** Stores a grant chain addressed to this node. */
+    addGrant(chain: Grant[]): Promise<void>;
+    /**
+     * Refuses the grant, and every grant delegated from it, in calls to this node, and stops its renewal.
+     * Name a grant this node issued by its id, and any other grant by its issuer and id.
+     */
+    revokeGrant(grant: string | GrantKey): Promise<void>;
+    /** Refuses this caller key in restricted calls, renewals, grant requests and paid calls. */
+    blockCaller(publicKey: string, reason?: string): Promise<void>;
+    /** False when the key wasn't blocked. */
+    unblockCaller(publicKey: string): Promise<boolean>;
+    private started;
 }
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAK9D,MAAM,WAAW,qBAAqB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,cAAc;IACvB,OAAO,CAAC,SAAS,CAA4B;IAEvC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAEK,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgCnF;CACJ"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -1,32 +1,133 @@
 import 'dotenv/config';
-import { createTables } from './db/db.js';
+import { DEFAULT_DATABASE_PATH, openDatabase } from './db/db.js';
 import routes from './routes.js';
 import { createService } from './service.js';
 import { StartupService } from './startup.js';
+export const DEFAULT_COST_LIMIT_LAMPORTS = 10_000;
+export const DEFAULT_GRANT_REFRESH_INTERVAL_MS = 1000 * 60 * 5;
+function required(name, value) {
+    if (!value) {
+        throw new Error(`${name} is required: pass it to StellariumNode.start or set it in the environment`);
+    }
+    return value;
+}
+function hostsPaidFunctions(resources) {
+    return resources.some(resource => resource.functions.some(fn => fn.paymentManifest));
+}
+export function resolveConfig(options, resources = []) {
+    const costLimit = options.costLimitLamports ?? (process.env.COST_LIMIT_LAMPORTS ? Number(process.env.COST_LIMIT_LAMPORTS) : DEFAULT_COST_LIMIT_LAMPORTS);
+    if (!Number.isSafeInteger(costLimit) || costLimit < 0) {
+        throw new Error('costLimitLamports must be a nonnegative integer');
+    }
+    return {
+        baseUrl: required('BASE_URL', options.baseUrl ?? process.env.BASE_URL),
+        publicKey: required('SIGNING_PUBLIC_KEY', options.publicKey ?? process.env.SIGNING_PUBLIC_KEY),
+        privateKey: required('SIGNING_PRIVATE_KEY', options.privateKey ?? process.env.SIGNING_PRIVATE_KEY),
+        apiKey: options.apiKey ?? process.env.API_KEY,
+        // Only a node hosting paid functions settles payments.
+        operatorUrl: hostsPaidFunctions(resources)
+            ? required('OPERATOR_URL', options.operatorUrl ?? process.env.OPERATOR_URL)
+            : options.operatorUrl ?? process.env.OPERATOR_URL,
+        costLimitLamports: costLimit,
+    };
+}
 export class StellariumNode {
     resources = [];
+    service;
     async register(resource) {
         this.resources.push(resource);
     }
+    /**
+     * Listens, then bootstraps from `startingPeer` if one is given.
+     * Rejects if the server can't listen or bootstrapping fails.
+     */
     async start(fastify, options) {
-        ;
-        const service = createService(this.resources);
-        await createTables();
-        fastify.register(routes, { prefix: '/v1', service });
-        // Run the server!
-        fastify.listen({ port: options.port ?? 3000, host: options.host ?? '0.0.0.0' }, function (err, address) {
-            if (err) {
-                fastify.log.error(err);
-                process.exit(1);
-            }
-            if (options.startingPeer) {
-                const startupService = new StartupService(fastify.log, service, options.startingPeer, process.env.BASE_URL, process.env.SIGNING_PUBLIC_KEY, process.env.SIGNING_PRIVATE_KEY);
-                Promise.resolve(startupService.seedFromPeer()).catch(err => {
-                    fastify.log.error(err);
-                    process.exit(1);
-                });
+        const config = resolveConfig(options, this.resources);
+        const db = await openDatabase(options.databasePath ?? DEFAULT_DATABASE_PATH);
+        fastify.addHook('onClose', async () => db.close());
+        const service = createService(db, this.resources, config, { approveGrant: options.approveGrant });
+        // A configured chain may be older than its stored renewal, or long expired; neither should stop the node.
+        for (const chain of options.grants ?? []) {
+            if (!await service.grantService.seed(chain)) {
+                fastify.log.warn(`Skipped expired grant ${chain[chain.length - 1]?.id} from the start options`);
             }
-            fastify.log.info(`server listening on ${address}`);
+        }
+        this.service = service;
+        // Each run is scheduled after the previous one finishes, so slow renewals never overlap.
+        const refreshIntervalMs = options.grantRefreshIntervalMs ?? DEFAULT_GRANT_REFRESH_INTERVAL_MS;
+        let refresher;
+        let closed = false;
+        const scheduleRefresh = () => {
+            refresher = setTimeout(async () => {
+                try {
+                    const { failed, removed } = await service.grantService.refreshDue();
+                    for (const { id, error } of failed) {
+                        fastify.log.warn(`Failed to renew grant ${id}: ${error}`);
+                    }
+                    for (const id of removed) {
+                        fastify.log.info(`Removed long-expired grant ${id}: its issuer refused renewal`);
+                    }
+                }
+                catch (error) {
+                    fastify.log.error(error, 'Failed to renew grants');
+                }
+                if (!closed) {
+                    scheduleRefresh();
+                }
+            }, refreshIntervalMs);
+            refresher.unref();
+        };
+        scheduleRefresh();
+        fastify.addHook('onClose', async () => {
+            closed = true;
+            clearTimeout(refresher);
         });
+        await fastify.register(routes, { prefix: '/v1', service, rateLimit: options.rateLimit });
+        const address = await fastify.listen({ port: options.port ?? 3000, host: options.host ?? '0.0.0.0' });
+        fastify.log.info(`server listening on ${address}`);
+        if (options.startingPeer) {
+            const startupService = new StartupService(fastify.log, service, options.startingPeer, config.baseUrl, config.publicKey, config.privateKey);
+            await startupService.seedFromPeer();
+        }
+    }
+    /** Issues a root grant for this node's resources. Hand the returned chain to the audience. */
+    async issueGrant(audience, capabilities, options) {
+        return this.started().grantService.issue(audience, capabilities, options);
+    }
+    /**
+     * Narrows a grant this node holds for another audience. Hand the returned chain to the audience.
+     * Name the held grant by its id, or by its issuer and id when two issuers used the same id.
+     */
+    async delegateGrant(heldGrant, audience, capabilities, options) {
+        return this.started().grantService.delegate(heldGrant, audience, capabilities, options);
+    }
+    /** Asks another node for a grant on its resources, and stores it. Throws if refused. */
+    async requestGrant(providerBaseUrl, capabilities, details) {
+        return this.started().grantService.request(providerBaseUrl, capabilities, details);
+    }
+    /** Stores a grant chain addressed to this node. */
+    async addGrant(chain) {
+        return this.started().grantService.add(chain);
+    }
+    /**
+     * Refuses the grant, and every grant delegated from it, in calls to this node, and stops its renewal.
+     * Name a grant this node issued by its id, and any other grant by its issuer and id.
+     */
+    async revokeGrant(grant) {
+        return this.started().grantService.revoke(grant);
+    }
+    /** Refuses this caller key in restricted calls, renewals, grant requests and paid calls. */
+    async blockCaller(publicKey, reason) {
+        return this.started().grantService.block(publicKey, reason);
+    }
+    /** False when the key wasn't blocked. */
+    async unblockCaller(publicKey) {
+        return this.started().grantService.unblock(publicKey);
+    }
+    started() {
+        if (!this.service) {
+            throw new Error('StellariumNode.start must be called first');
+        }
+        return this.service;
     }
 }