stellarium-ts 0.11.0 → 0.13.0

package/dist/grant/service.js

@@ -0,0 +1,431 @@
+import { isFreshExpiry, isValidPublicKey, safeVerifyData, signData } from "../crypto/utils.js";
+import { invocationHash } from "../resource/invoker.js";
+import { capabilityCovers, capabilityMatches, CLOCK_SKEW_TOLERANCE_MS, grantHash, grantRenewalPayload, grantRequestPayload, grantsHash, invocationAuthorizationPayload, isAuthorization, isCapability, isGrant, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, signGrant, verifyChain, } from "./grant.js";
+/** Per grant request or renewal. */
+export const GRANT_RENEW_TIMEOUT_MS = 10_000;
+/**
+ * How long a held chain is kept after it expires while its issuer refuses to renew it. A refusal
+ * may be temporary, such as while this node's key is blocked, so chains aren't deleted at once.
+ */
+export const HELD_GRANT_RETENTION_MS = MAX_GRANT_LIFETIME_MS;
+/** How often claiming a nonce also deletes expired ones. */
+const NONCE_SWEEP_INTERVAL_MS = 60_000;
+/** Most renewals `refreshDue` has in flight at once. */
+const REFRESH_CONCURRENCY = 8;
+/** Thrown by `block` for a key that isn't an Ed25519 SPKI key. */
+export class InvalidPublicKeyError extends Error {
+    constructor() {
+        super('Invalid public key');
+    }
+}
+/** Another node answered a grant request or renewal with a refusal, as opposed to failing to answer. */
+class GrantRefusedError extends Error {
+}
+const expired = (grant, now = Date.now()) => Date.parse(grant.expiresAt) <= now;
+const leafOf = (chain) => chain[chain.length - 1];
+const keyOf = (grant) => ({ issuer: grant.issuer, id: grant.id });
+const heldKey = (chain) => keyOf(leafOf(chain));
+/** The root grant's issuer, or `''` when the chain is malformed, so that `verifyChain` refuses it. */
+const rootIssuer = (chain) => Array.isArray(chain) && isGrant(chain[0]) ? chain[0].issuer : '';
+const isWellFormed = (chain) => Array.isArray(chain) && chain.length > 0 && chain.every(isGrant);
+/** True when `renewed` holds the same grants as `chain`, position by position. Renewal keeps each grant's issuer and id. */
+const sameGrants = (renewed, chain) => renewed.length === chain.length && renewed.every((grant, index) => grant.issuer === chain[index].issuer && grant.id === chain[index].id);
+/**
+ * Issues, holds, renews and verifies capability grants. Every node plays all three roles:
+ * a provider issues root grants, a holder can delegate narrower grants and renew them for
+ * its own audiences, and renewal of either kind goes through `renew`.
+ */
+export class GrantService {
+    repository;
+    config;
+    approveGrant;
+    lastNonceSweep = 0;
+    /** Without `approveGrant`, this node refuses every grant request. */
+    constructor(repository, config, approveGrant) {
+        this.repository = repository;
+        this.config = config;
+        this.approveGrant = approveGrant;
+    }
+    get acceptsRequests() {
+        return this.approveGrant !== undefined;
+    }
+    /** Issues a root grant for this node's resources. Returns it as a one-grant chain. */
+    async issue(audience, capabilities, options) {
+        checkCapabilities(capabilities);
+        checkOptions(options);
+        const grant = this.sign(crypto.randomUUID(), audience, capabilities, options.lifetimeMs, null, options.renewableUntil ?? null);
+        await this.repository.saveIssued({ id: grant.id, audience, capabilities, parent: null, lifetimeMs: options.lifetimeMs, renewableUntil: options.renewableUntil ?? null });
+        return [grant];
+    }
+    /**
+     * Narrows a grant this node holds for another audience. The child expires no later than the
+     * held grant. Name the held grant by its id, or by its issuer and id when two issuers used the same id.
+     */
+    async delegate(heldGrant, audience, capabilities, options) {
+        checkCapabilities(capabilities);
+        checkOptions(options);
+        const chain = await this.findHeld(heldGrant);
+        if (expired(leafOf(chain))) {
+            throw new Error(`No unexpired held grant ${leafOf(chain).id}`);
+        }
+        if (chain.length >= MAX_GRANT_CHAIN_LENGTH) {
+            throw new Error(`Grant chains are limited to ${MAX_GRANT_CHAIN_LENGTH} grants`);
+        }
+        const parent = leafOf(chain);
+        if (!capabilities.every(child => parent.capabilities.some(capability => capabilityCovers(capability, child)))) {
+            throw new Error('A delegated grant may only narrow the grant it is delegated from');
+        }
+        const grant = this.sign(crypto.randomUUID(), audience, capabilities, options.lifetimeMs, parent, options.renewableUntil ?? null);
+        await this.repository.saveIssued({ id: grant.id, audience, capabilities, parent: heldKey(chain), lifetimeMs: options.lifetimeMs, renewableUntil: options.renewableUntil ?? null });
+        return [...chain, grant];
+    }
+    /**
+     * Revoked grants are refused in any chain this node verifies, and are never renewed. A
+     * delegator's revocation only stops renewal, since the provider never sees it, so it
+     * takes effect when the current copy expires. Name a grant this node issued by its id, and
+     * any other grant, such as one delegated further down a chain, by its issuer and id.
+     */
+    async revoke(grant) {
+        await this.repository.revoke(typeof grant === 'string' ? { issuer: this.config.publicKey, id: grant } : grant);
+    }
+    /**
+     * Refuses `publicKey` everywhere this node can identify a caller: in any position of a
+     * restricted call's chain, and in renewals, grant requests and payment vouchers.
+     */
+    async block(publicKey, reason) {
+        if (!isValidPublicKey(publicKey)) {
+            throw new InvalidPublicKeyError();
+        }
+        await this.repository.block(publicKey, reason ?? null);
+    }
+    /** False when the key wasn't blocked. */
+    async unblock(publicKey) {
+        return this.repository.unblock(publicKey);
+    }
+    async isBlocked(publicKey) {
+        return this.repository.anyBlocked([publicKey]);
+    }
+    async getBlocked(offset, limit) {
+        return this.repository.getBlocked(offset, limit);
+    }
+    /** Handles a holder's renewal request for a grant this node issued. Returns the fresh chain, or undefined if refused. */
+    async renew(request) {
+        // A replayed request only hands the audience another copy that it alone can use, so nonces aren't tracked.
+        if (!isFreshExpiry(request.expiresAt, MAX_AUTHORIZATION_LIFETIME_MS + CLOCK_SKEW_TOLERANCE_MS) || !safeVerifyData(grantRenewalPayload(request), request.publicKey, request.signature)) {
+            return undefined;
+        }
+        const issued = await this.repository.getIssued(request.grantId);
+        if (!issued || issued.audience !== request.publicKey || await this.isBlocked(request.publicKey)) {
+            return undefined;
+        }
+        if (issued.renewableUntil !== null && Date.parse(issued.renewableUntil) <= Date.now()) {
+            return undefined;
+        }
+        let chain = [];
+        if (issued.parent !== null) {
+            const held = await this.repository.getHeld(issued.parent);
+            if (!held || expired(leafOf(held))) {
+                return undefined;
+            }
+            chain = held;
+        }
+        if (await this.repository.anyRevoked([{ issuer: this.config.publicKey, id: issued.id }, ...chain.map(keyOf)])) {
+            return undefined;
+        }
+        const parent = chain.length > 0 ? leafOf(chain) : null;
+        return [...chain, this.sign(issued.id, issued.audience, issued.capabilities, issued.lifetimeMs, parent, issued.renewableUntil)];
+    }
+    /**
+     * Handles a caller's request for a new root grant: checks its signature and nonce, then
+     * asks the approval hook. Returns the issued chain, or undefined if refused. Throws if the
+     * hook throws or returns an invalid approval; the caller must then sign a new request.
+     */
+    async handleRequest(request) {
+        if (!this.approveGrant) {
+            return undefined;
+        }
+        const { publicKey, capabilities, nonce, expiresAt, signature } = request;
+        const details = request.details ?? null;
+        if (!validCapabilities(capabilities)) {
+            return undefined;
+        }
+        if (details !== null && (typeof details !== 'object' || Array.isArray(details))) {
+            return undefined;
+        }
+        if (!isFreshExpiry(expiresAt, MAX_AUTHORIZATION_LIFETIME_MS + CLOCK_SKEW_TOLERANCE_MS) || !safeVerifyData(grantRequestPayload(request), publicKey, signature)) {
+            return undefined;
+        }
+        if (await this.isBlocked(publicKey)) {
+            return undefined;
+        }
+        // The hook may have side effects, such as using up an invite code, so it sees each request once.
+        if (!await this.claimNonce(`request:${publicKey}`, nonce, Date.parse(expiresAt))) {
+            return undefined;
+        }
+        const approval = await this.approveGrant({ publicKey, capabilities, details });
+        if (!approval) {
+            return undefined;
+        }
+        const granted = approval.capabilities ?? capabilities;
+        try {
+            checkCapabilities(granted);
+            checkOptions(approval);
+        }
+        catch (error) {
+            throw new Error(`approveGrant returned an invalid approval: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return this.issue(publicKey, granted, approval);
+    }
+    /**
+     * Asks the node at `providerBaseUrl` for a root grant and stores it. Throws if refused.
+     * The provider verifies the grant again on every call, so a grant from the wrong key only fails there.
+     */
+    async request(providerBaseUrl, capabilities, details) {
+        const unsigned = { publicKey: this.config.publicKey, capabilities, details: details ?? null, nonce: crypto.randomUUID(), expiresAt: new Date(Date.now() + MAX_AUTHORIZATION_LIFETIME_MS).toISOString() };
+        const request = { ...unsigned, signature: signData(grantRequestPayload(unsigned), this.config.privateKey) };
+        const grants = await this.postForGrants(`${providerBaseUrl}/v1/grants/request`, request, `Grant request to ${providerBaseUrl}`);
+        const chain = verifyChain(grants, rootIssuer(grants));
+        if (!chain.ok || grants.length !== 1 || grants[0].issuerBaseUrl !== providerBaseUrl || chain.leaf.audience !== this.config.publicKey) {
+            throw new Error(`Grant request to ${providerBaseUrl} returned an invalid grant`);
+        }
+        await this.repository.saveHeld(grants);
+        return grants;
+    }
+    /** Stores a chain whose leaf names this node as its audience. Throws if the chain is invalid. */
+    async add(chain) {
+        const result = verifyChain(chain, rootIssuer(chain));
+        if (!result.ok) {
+            throw new Error(`Invalid grant chain: ${result.reason}`);
+        }
+        if (result.leaf.audience !== this.config.publicKey) {
+            throw new Error('Grant chain is not addressed to this node');
+        }
+        await this.repository.saveHeld(chain);
+    }
+    /**
+     * Stores a chain passed in the node's start options. A held copy of the same grant that
+     * expires no earlier is a renewal of it, so it is kept. Returns false, storing nothing, for
+     * an expired chain. Throws if the chain is otherwise invalid.
+     */
+    async seed(chain) {
+        if (isWellFormed(chain)) {
+            const held = await this.repository.getHeld(heldKey(chain));
+            if (held && Date.parse(leafOf(held).expiresAt) >= Date.parse(leafOf(chain).expiresAt)) {
+                return true;
+            }
+            // No grant in a valid chain outlives its parent, so the leaf expires first.
+            if (expired(leafOf(chain))) {
+                return false;
+            }
+        }
+        await this.add(chain);
+        return true;
+    }
+    /**
+     * A held chain, rooted at the node serving `rootBaseUrl`, that covers the call. When every
+     * such chain has expired, the latest-expiring one is renewed, once, before giving up, so a
+     * call waits on at most one renewal. Undefined when this node holds no usable grant.
+     */
+    async chainFor(rootBaseUrl, target) {
+        const now = Date.now();
+        // The provider refuses a chain from a key it no longer uses, such as after a key rotation.
+        // When this node doesn't know the provider as a peer, chains from any root key are tried.
+        const rootKey = await this.repository.getPeerKey(rootBaseUrl);
+        const usable = (chain) => (rootKey === undefined || chain[0].issuer === rootKey)
+            && leafOf(chain).capabilities.some(capability => capabilityMatches(capability, target.resourcePath, target.resourceName, target.functionName, target.parameters));
+        const chain = (await this.repository.getUnexpiredHeldByRoot(rootBaseUrl, now)).find(usable);
+        if (chain) {
+            return chain;
+        }
+        const latestExpired = (await this.repository.getExpiredHeldByRoot(rootBaseUrl, now)).find(usable);
+        if (!latestExpired) {
+            return undefined;
+        }
+        try {
+            return await this.renewHeld(latestExpired);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Builds the authorization sent with a call. Sign a new one per attempt: providers refuse a reused nonce. */
+    authorize(chain, target) {
+        const nonce = crypto.randomUUID();
+        const expiresAt = new Date(Date.now() + MAX_AUTHORIZATION_LIFETIME_MS).toISOString();
+        const hash = invocationHash(target.resourcePath, target.resourceName, target.functionName, target.parameters);
+        const signature = signData(invocationAuthorizationPayload({ invocationHash: hash, publicKey: this.config.publicKey, nonce, expiresAt, grantsHash: grantsHash(chain) }), this.config.privateKey);
+        return { publicKey: this.config.publicKey, grants: chain, nonce, expiresAt, signature };
+    }
+    /**
+     * Renews every held chain past half its lifetime. A failed renewal keeps the current copy,
+     * unless the issuer refused it and the chain expired more than `HELD_GRANT_RETENTION_MS` ago.
+     */
+    async refreshDue() {
+        const now = Date.now();
+        const due = (await this.repository.getAllHeld()).filter(chain => {
+            const leaf = leafOf(chain);
+            const issuedAt = Date.parse(leaf.issuedAt);
+            return now >= issuedAt + (Date.parse(leaf.expiresAt) - issuedAt) / 2;
+        });
+        const outcomes = [];
+        const refresh = async (chain) => {
+            const leaf = leafOf(chain);
+            try {
+                await this.renewHeld(chain);
+                return { renewed: leaf.id };
+            }
+            catch (error) {
+                if (error instanceof GrantRefusedError && expired(leaf, now - HELD_GRANT_RETENTION_MS)) {
+                    await this.repository.deleteHeld(heldKey(chain));
+                    return { removed: leaf.id };
+                }
+                return { failed: { id: leaf.id, error: error instanceof Error ? error.message : String(error) } };
+            }
+        };
+        let next = 0;
+        const worker = async () => {
+            while (next < due.length) {
+                const index = next++;
+                outcomes[index] = await refresh(due[index]);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(REFRESH_CONCURRENCY, due.length) }, worker));
+        const result = { renewed: [], failed: [], removed: [] };
+        for (const outcome of outcomes) {
+            if ('renewed' in outcome) {
+                result.renewed.push(outcome.renewed);
+            }
+            else if ('removed' in outcome) {
+                result.removed.push(outcome.removed);
+            }
+            else {
+                result.failed.push(outcome.failed);
+            }
+        }
+        return result;
+    }
+    /**
+     * True when `authorization` lets its signer make exactly this call: the chain is rooted at
+     * this node, unrevoked, addressed to the signer and covers the call, and the nonce is new.
+     */
+    async verifyInvocation(authorization, target) {
+        if (!isAuthorization(authorization) || !isFreshExpiry(authorization.expiresAt, MAX_AUTHORIZATION_LIFETIME_MS + CLOCK_SKEW_TOLERANCE_MS)) {
+            return false;
+        }
+        const chain = verifyChain(authorization.grants, this.config.publicKey);
+        if (!chain.ok || chain.leaf.audience !== authorization.publicKey) {
+            return false;
+        }
+        const hash = invocationHash(target.resourcePath, target.resourceName, target.functionName, target.parameters);
+        const payload = invocationAuthorizationPayload({ invocationHash: hash, publicKey: authorization.publicKey, nonce: authorization.nonce, expiresAt: authorization.expiresAt, grantsHash: grantsHash(authorization.grants) });
+        if (!safeVerifyData(payload, authorization.publicKey, authorization.signature)) {
+            return false;
+        }
+        if (!chain.leaf.capabilities.some(capability => capabilityMatches(capability, target.resourcePath, target.resourceName, target.functionName, target.parameters))) {
+            return false;
+        }
+        if (await this.repository.anyRevoked(authorization.grants.map(keyOf))) {
+            return false;
+        }
+        // Every audience in the chain, so blocking a delegator also cuts off what it handed on.
+        if (await this.repository.anyBlocked(authorization.grants.map(grant => grant.audience))) {
+            return false;
+        }
+        return this.claimNonce(authorization.publicKey, authorization.nonce, Date.parse(authorization.expiresAt));
+    }
+    /**
+     * Nonces are kept in the node's database, so they survive a restart. Replicas of a node that
+     * don't share a database don't see each other's nonces.
+     */
+    async claimNonce(publicKey, nonce, expiresAt) {
+        const now = Date.now();
+        if (now - this.lastNonceSweep >= NONCE_SWEEP_INTERVAL_MS) {
+            this.lastNonceSweep = now;
+            await this.repository.deleteExpiredNonces(now);
+        }
+        return this.repository.claimNonce(`${publicKey}:${nonce}`, expiresAt);
+    }
+    async findHeld(heldGrant) {
+        if (typeof heldGrant !== 'string') {
+            const chain = await this.repository.getHeld(heldGrant);
+            if (!chain) {
+                throw new Error(`No held grant ${heldGrant.id} from ${heldGrant.issuer}`);
+            }
+            return chain;
+        }
+        const chains = await this.repository.getHeldById(heldGrant);
+        if (chains.length === 0) {
+            throw new Error(`No held grant ${heldGrant}`);
+        }
+        if (chains.length > 1) {
+            throw new Error(`Several issuers gave this node a grant with id ${heldGrant}: name the issuer too`);
+        }
+        return chains[0];
+    }
+    /** Asks the leaf grant's issuer for a fresh chain and stores it. Throws if refused or invalid. */
+    async renewHeld(chain) {
+        const leaf = leafOf(chain);
+        const unsigned = { grantId: leaf.id, publicKey: this.config.publicKey, nonce: crypto.randomUUID(), expiresAt: new Date(Date.now() + MAX_AUTHORIZATION_LIFETIME_MS).toISOString() };
+        const request = { ...unsigned, signature: signData(grantRenewalPayload(unsigned), this.config.privateKey) };
+        const grants = await this.postForGrants(`${leaf.issuerBaseUrl}/v1/grants/renew`, request, `Renewal of grant ${leaf.id}`);
+        // The issuer may not swap in a different grant, root or chain, so the renewal replaces the held copy.
+        const renewed = verifyChain(grants, chain[0].issuer);
+        if (!renewed.ok || !sameGrants(grants, chain) || renewed.leaf.audience !== this.config.publicKey) {
+            throw new Error(`Renewal of grant ${leaf.id} returned an invalid chain`);
+        }
+        await this.repository.saveHeld(grants);
+        return grants;
+    }
+    /**
+     * POSTs a signed request to another node's grant endpoint and returns the chain it answered
+     * with, unverified. Throws `GrantRefusedError` if the node refused, and an Error if it failed.
+     */
+    async postForGrants(url, body, description) {
+        const response = await fetch(url, {
+            method: 'POST',
+            body: JSON.stringify(body),
+            headers: { 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(GRANT_RENEW_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            const detail = await response.json().then((answer) => answer?.error, () => undefined);
+            const reason = typeof detail === 'string' ? detail : response.status;
+            throw response.status === 403 ? new GrantRefusedError(`${description} refused: ${reason}`) : new Error(`${description} failed: ${reason}`);
+        }
+        const answer = await response.json();
+        return answer?.grants;
+    }
+    /** The copy expires after `lifetimeMs`, but no later than its parent or `renewableUntil`. */
+    sign(id, audience, capabilities, lifetimeMs, parent, renewableUntil) {
+        const now = Date.now();
+        const expiresAt = Math.min(now + lifetimeMs, parent ? Date.parse(parent.expiresAt) : Infinity, renewableUntil !== null ? Date.parse(renewableUntil) : Infinity);
+        return signGrant({
+            id,
+            issuer: this.config.publicKey,
+            issuerBaseUrl: this.config.baseUrl,
+            audience,
+            capabilities,
+            issuedAt: new Date(now).toISOString(),
+            expiresAt: new Date(expiresAt).toISOString(),
+            parent: parent ? grantHash(parent) : null,
+        }, this.config.privateKey);
+    }
+}
+/** Verifiers refuse a grant with no capabilities or a malformed one, so it is never signed. */
+function validCapabilities(capabilities) {
+    return Array.isArray(capabilities) && capabilities.length > 0 && capabilities.every(isCapability);
+}
+function checkCapabilities(capabilities) {
+    if (!validCapabilities(capabilities)) {
+        throw new Error('capabilities must be a nonempty list of capabilities, each with a resourcePath');
+    }
+}
+function checkOptions(options) {
+    if (!Number.isSafeInteger(options.lifetimeMs) || options.lifetimeMs <= 0 || options.lifetimeMs > MAX_GRANT_LIFETIME_MS) {
+        throw new Error(`lifetimeMs must be a positive integer of at most ${MAX_GRANT_LIFETIME_MS}`);
+    }
+    // A grant expires by renewableUntil, so a past one would only sign an expired grant.
+    if (options.renewableUntil !== undefined && !(Date.parse(options.renewableUntil) > Date.now())) {
+        throw new Error('renewableUntil must be a future date');
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-export { StellariumNode, type StellariumNodeOptions } from './server.js';
+export { StellariumNode, resolveConfig, type StellariumNodeOptions } from './server.js';
+export type { NodeConfig } from './service.js';
 export type { StellariumResource, StellariumResourceFunction, StellariumResourceFunctionPaymentManifest } from './resource/repository.js';
+export { CombinationResourceInvoker, invocationHash, paymentVoucherPayload, type PaymentVoucher } from './resource/invoker.js';
+export { grantHash, grantPayload, grantRenewalPayload, grantRequestPayload, grantsHash, CLOCK_SKEW_TOLERANCE_MS, invocationAuthorizationPayload, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, type Capability, type Grant, type GrantRenewalRequest, type GrantRequest, type InvocationAuthorization, } from './grant/grant.js';
+export type { ApproveGrant, GrantApproval, GrantOptions } from './grant/service.js';
+export type { GrantKey } from './grant/repository.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,0BAA0B,CAAC;AAE1I,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/H,OAAO,EACH,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1 +1,5 @@
-export { StellariumNode } from './server.js';
+export { StellariumNode, resolveConfig } from './server.js';
+// The voucher wire format, so the operator and other settlers can test against the real signer.
+export { CombinationResourceInvoker, invocationHash, paymentVoucherPayload } from './resource/invoker.js';
+// Grant wire format, so other implementations can test against the real signer.
+export { grantHash, grantPayload, grantRenewalPayload, grantRequestPayload, grantsHash, CLOCK_SKEW_TOLERANCE_MS, invocationAuthorizationPayload, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, } from './grant/grant.js';

package/dist/peer/repository.d.ts

@@ -4,13 +4,44 @@ export interface Peer {
     name: string;
     publicKey: string;
 }
+export interface StoredPeer extends Peer {
+    id: number;
+}
+/** Why `announce` rejected a peer. */
+export type PeerAnnouncementError = 'invalid_signature' | 'conflict';
+/**
+ * The object a node signs to announce itself. Including `publicKey` binds the
+ * announcement to the key that signed it. Key order is part of the signed bytes.
+ */
+export declare function peerAnnouncementPayload(peer: Peer, expiry: string): {
+    baseUrl: string;
+    name: string;
+    publicKey: string;
+    expiry: string;
+};
 export declare class PeerRepository {
     private readonly db;
     constructor(db: Database);
+    /**
+     * Saves a peer learned from a trusted source (the starting peer) without a signature.
+     * Does nothing if a peer with the same public key, base URL or name already exists.
+     */
     create(peer: Peer): Promise<void>;
-    createIfNotExists(peer: Peer, signature: string, expiry: string): Promise<void>;
+    /**
+     * Saves a peer that announced itself. The announcement must be signed by `peer.publicKey`.
+     * A known peer (same public key) may change its base URL and name; a new peer may not
+     * take a base URL or name that another peer already holds.
+     */
+    announce(peer: Peer, signature: string, expiry: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: PeerAnnouncementError;
+    }>;
     deleteAll(): Promise<void>;
     getPeerList(): Promise<Peer[]>;
-    getPeerByPublicKey(publicKey: string): Promise<Peer | undefined>;
+    /** One page of peers, in insertion order so offsets stay stable as peers are added. */
+    getPeers(offset: number, limit: number): Promise<Peer[]>;
+    getPeerByPublicKey(publicKey: string): Promise<StoredPeer | undefined>;
 }
 //# sourceMappingURL=repository.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/peer/repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,MAAM,WAAW,IAAI;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;IAA/B,YAA6B,EAAE,EAAE,QAAQ,EAAI;IAEvC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBtC;IAEK,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBpF;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/B;IAEK,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAQnC;IAEK,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAQrE;CACJ"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/peer/repository.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,MAAM,WAAW,IAAI;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI;IACpC,EAAE,EAAE,MAAM,CAAC;CACd;AAED,sCAAsC;AACtC,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,UAAU,CAAC;AAErE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM;;;;;EAGjE;AAaD,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;IAA/B,YAA6B,EAAE,EAAE,QAAQ,EAAI;IAE7C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtC;IAED;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAoBjI;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAE/B;IAEK,WAAW,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAQnC;IAED,uFAAuF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAQ7D;IAEK,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAG3E;CACJ"}

package/dist/peer/repository.js

@@ -1,29 +1,45 @@
-import { verifyData } from "../crypto/utils.js";
+import { isFreshExpiry, safeVerifyData } from "../crypto/utils.js";
+/**
+ * The object a node signs to announce itself. Including `publicKey` binds the
+ * announcement to the key that signed it. Key order is part of the signed bytes.
+ */
+export function peerAnnouncementPayload(peer, expiry) {
+    const { baseUrl, name, publicKey } = peer;
+    return { baseUrl, name, publicKey, expiry };
+}
+function toPeer(row) {
+    return { id: row.id, baseUrl: row.base_url, name: row.name, publicKey: row.public_key };
+}
 export class PeerRepository {
     db;
     constructor(db) {
         this.db = db;
     }
+    /**
+     * Saves a peer learned from a trusted source (the starting peer) without a signature.
+     * Does nothing if a peer with the same public key, base URL or name already exists.
+     */
     async create(peer) {
-        // Check if the peer already exists
-        const existingPeer = await this.db.get('SELECT * FROM peer WHERE base_url = ?', [peer.baseUrl]);
-        if (existingPeer) {
-            return;
-        }
         const createdAt = new Date().toISOString();
-        await this.db.run('INSERT INTO peer (base_url, name, public_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [peer.baseUrl, peer.name, peer.publicKey, createdAt, createdAt]);
+        await this.db.run('INSERT OR IGNORE INTO peer (base_url, name, public_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [peer.baseUrl, peer.name, peer.publicKey, createdAt, createdAt]);
     }
-    async createIfNotExists(peer, signature, expiry) {
-        const existingPeer = await this.db.get('SELECT * FROM peer WHERE base_url = ?', [peer.baseUrl]);
-        // If the peer already exists, verify the signature before updating.
-        if (existingPeer) {
-            if (verifyData({ ...peer, expiry }, existingPeer.publicKey, signature) && new Date(expiry) > new Date()) {
-                await this.db.run('UPDATE peer SET base_url = ?, name = ?, updated_at = ? WHERE public_key = ?', [peer.baseUrl, peer.name, new Date().toISOString(), peer.publicKey]);
-                return;
-            }
-            return;
+    /**
+     * Saves a peer that announced itself. The announcement must be signed by `peer.publicKey`.
+     * A known peer (same public key) may change its base URL and name; a new peer may not
+     * take a base URL or name that another peer already holds.
+     */
+    async announce(peer, signature, expiry) {
+        if (!isFreshExpiry(expiry) || !safeVerifyData(peerAnnouncementPayload(peer, expiry), peer.publicKey, signature)) {
+            return { ok: false, error: 'invalid_signature' };
         }
-        await this.create(peer);
+        const holder = await this.db.get('SELECT * FROM peer WHERE (base_url = ? OR name = ?) AND public_key != ?', [peer.baseUrl, peer.name, peer.publicKey]);
+        if (holder) {
+            return { ok: false, error: 'conflict' };
+        }
+        const now = new Date().toISOString();
+        await this.db.run(`INSERT INTO peer (base_url, name, public_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?)
+             ON CONFLICT (public_key) DO UPDATE SET base_url = excluded.base_url, name = excluded.name, updated_at = excluded.updated_at`, [peer.baseUrl, peer.name, peer.publicKey, now, now]);
+        return { ok: true };
     }
     async deleteAll() {
         await this.db.run('DELETE FROM peer');
@@ -36,11 +52,17 @@ export class PeerRepository {
             publicKey: result.public_key,
         }));
     }
+    /** One page of peers, in insertion order so offsets stay stable as peers are added. */
+    async getPeers(offset, limit) {
+        const results = await this.db.all('SELECT * FROM peer ORDER BY id LIMIT ? OFFSET ?', [limit, offset]);
+        return results.map(result => ({
+            baseUrl: result.base_url,
+            name: result.name,
+            publicKey: result.public_key,
+        }));
+    }
     async getPeerByPublicKey(publicKey) {
         const result = await this.db.get('SELECT * FROM peer WHERE public_key = ?', [publicKey]);
-        if (result) {
-            return result;
-        }
-        return undefined;
+        return result ? toPeer(result) : undefined;
     }
 }

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