stellarium-ts 0.16.0 → 0.18.0

package/dist/client/operatorAuth.d.ts

@@ -0,0 +1,19 @@
+/** The scheme of the `Authorization` header on node requests to the operator. */
+export declare const OPERATOR_AUTH_SCHEME = "Stellarium";
+/**
+ * The object a node signs to authenticate one operator request. `path` is the URL path without the
+ * query string, and `bodyHash` is `hashData` of the parsed JSON body (`{}` when there is none).
+ * Key order is part of the signed bytes. The operator rebuilds this in apps/operator/src/auth/nodeAuth.ts.
+ */
+export declare function operatorRequestPayload(method: string, path: string, body: unknown, timestamp: string): {
+    method: string;
+    path: string;
+    bodyHash: string;
+    timestamp: string;
+};
+/**
+ * `Authorization` header value for a request to `url`: the scheme, then base64url JSON of
+ * `{ publicKey, timestamp, signature }`. The operator accepts timestamps within a few minutes of its clock.
+ */
+export declare function operatorAuthorization(method: string, url: string, body: unknown, publicKey: string, privateKey: string): string;
+//# sourceMappingURL=operatorAuth.d.ts.map

package/dist/client/operatorAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operatorAuth.d.ts","sourceRoot":"","sources":["../../src/client/operatorAuth.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM;;;;;EAEpG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK/H"}

package/dist/client/operatorAuth.js

@@ -0,0 +1,21 @@
+import { hashData, signData } from "../crypto/utils.js";
+/** The scheme of the `Authorization` header on node requests to the operator. */
+export const OPERATOR_AUTH_SCHEME = 'Stellarium';
+/**
+ * The object a node signs to authenticate one operator request. `path` is the URL path without the
+ * query string, and `bodyHash` is `hashData` of the parsed JSON body (`{}` when there is none).
+ * Key order is part of the signed bytes. The operator rebuilds this in apps/operator/src/auth/nodeAuth.ts.
+ */
+export function operatorRequestPayload(method, path, body, timestamp) {
+    return { method: method.toUpperCase(), path, bodyHash: hashData(body ?? {}), timestamp };
+}
+/**
+ * `Authorization` header value for a request to `url`: the scheme, then base64url JSON of
+ * `{ publicKey, timestamp, signature }`. The operator accepts timestamps within a few minutes of its clock.
+ */
+export function operatorAuthorization(method, url, body, publicKey, privateKey) {
+    const timestamp = new Date().toISOString();
+    const signature = signData(operatorRequestPayload(method, new URL(url).pathname, body, timestamp), privateKey);
+    const credentials = Buffer.from(JSON.stringify({ publicKey, timestamp, signature })).toString('base64url');
+    return `${OPERATOR_AUTH_SCHEME} ${credentials}`;
+}

package/dist/client/operatorClient.d.ts

@@ -1,48 +1,120 @@
 export type PaymentSubmission = FixedPaymentSubmission | InferencePaymentSubmission;
+export interface FixedPaymentVoucher {
+    kind?: undefined;
+    requestId: string;
+    invocationId: string;
+    amount: number;
+    recipientOrganizationId: string;
+    signature: string;
+    expiresAt: string;
+    invocationHash: string;
+    publicKey: string;
+    runId?: string;
+}
+export interface InferenceVoucher {
+    kind: 'inference';
+    requestId: string;
+    invocationId: string;
+    maxAmount: number;
+    inputCostMicroUsdPerMillionTokens: number;
+    outputCostMicroUsdPerMillionTokens: number;
+    maxTokens: number;
+    recipientOrganizationId: string;
+    signature: string;
+    expiresAt: string;
+    invocationHash: string;
+    publicKey: string;
+    runId?: string;
+}
 export interface FixedPaymentSubmission {
-    voucher: {
-        requestId: string;
-        invocationId: string;
-        amount: number;
-        recipientAddress: string;
-        signature: string;
-        expiresAt: string;
-        invocationHash: string;
-        publicKey: string;
-    };
+    voucher: FixedPaymentVoucher;
 }
-/** The provider reports the call's usage; the operator charges it at the voucher's rates, up to `maxAmount`. */
+/** The provider reports the call's usage; the operator charges it at the voucher's rates, up to the held `maxAmount`. */
 export interface InferencePaymentSubmission {
-    voucher: {
-        kind: 'inference';
-        requestId: string;
-        invocationId: string;
-        maxAmount: number;
-        inputCostMicroUsdcPerMillionTokens: number;
-        outputCostMicroUsdcPerMillionTokens: number;
-        maxTokens: number;
-        recipientAddress: string;
-        signature: string;
-        expiresAt: string;
-        invocationHash: string;
-        publicKey: string;
-    };
+    voucher: InferenceVoucher;
     usage: {
         inputTokens: number;
         outputTokens: number;
     };
 }
-export declare const SETTLE_PAYMENT_MAX_RETRIES = 5;
-export declare const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
+/** Whether the operator placed a hold for a voucher. A refusal carries the operator's status and error. */
+export type AuthorizeResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** What a node sends to authorize a script run billed to an API client. Matches apps/operator/src/runs/runService.ts. */
+export interface RunAuthorizationRequest {
+    /** The run token the caller presented. */
+    token: string;
+    runId: string;
+    source: string;
+}
+/** The operator's hold for a run: up to `heldMicroUsd` for the script's tokens and its paid calls together. */
+export type RunAuthorizeResult = {
+    ok: true;
+    heldMicroUsd: number;
+    maxTokens: number;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+export declare const OPERATOR_MAX_RETRIES = 5;
+/** Authorization runs while the caller waits, so it gives up much sooner than capture and release. */
+export declare const AUTHORIZE_MAX_RETRIES = 2;
+export declare const OPERATOR_BASE_DELAY_MS = 1000;
+export declare const AUTHORIZE_BASE_DELAY_MS = 200;
 /** Per attempt. A timed-out attempt is retried like a network error. */
-export declare const SETTLE_PAYMENT_TIMEOUT_MS = 10000;
+export declare const OPERATOR_TIMEOUT_MS = 10000;
+/** Talks to the operator as this node. Every request is signed with the node's key. */
 export declare class OperatorClient {
     private readonly url;
-    constructor(url: string | undefined);
+    private readonly publicKey;
+    private readonly privateKey;
+    constructor(url: string | undefined, publicKey: string, privateKey: string);
     /**
-     * Retries `RETRYABLE_STATUSES` and network errors up to `SETTLE_PAYMENT_MAX_RETRIES` times.
+     * POSTs `body`, retrying `RETRYABLE_STATUSES` and network errors up to `retries` times.
+     * Each attempt is signed afresh, since the operator only accepts recent timestamps.
      * Throws the last network error if the operator could not be reached, or if no operator URL is configured.
      */
-    settlePayment(payment: PaymentSubmission): Promise<void>;
+    private post;
+    /**
+     * Returns the organization this node is enrolled in. With an `enrollmentToken` from the dashboard,
+     * enrolls the node first; a node that is already enrolled ignores the token. Throws if the node is
+     * not enrolled or the operator refuses.
+     */
+    session(enrollmentToken?: string, baseUrl?: string): Promise<{
+        organizationId: string;
+    }>;
+    /**
+     * Asks the operator to hold the voucher's amount (or `maxAmount`) on the payer's balance, before
+     * running the paid function. An unreachable operator is reported as a 503 refusal.
+     */
+    authorize(voucher: FixedPaymentVoucher | InferenceVoucher): Promise<AuthorizeResult>;
+    /**
+     * Asks the operator to hold a script run's cost on the paying API client's organization, before running
+     * it. An unreachable operator is reported as a 503 refusal.
+     */
+    authorizeRun(request: RunAuthorizationRequest): Promise<RunAuthorizeResult>;
+    /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
+    captureRun(request: {
+        runId: string;
+        tokens: number;
+    }): Promise<void>;
+    /** Releases a held run without charging it, for a script this node failed to run. */
+    releaseRun(request: {
+        runId: string;
+    }): Promise<void>;
+    /** Authorization runs while the caller waits, so it retries briefly and reports an unreachable operator as 503. */
+    private hold;
+    /** Charges a held voucher: its amount, or for inference the reported usage capped at the hold. */
+    capture(payment: PaymentSubmission): Promise<void>;
+    /** Releases a held voucher without charging it, for a call that failed or cost nothing. */
+    release(voucher: FixedPaymentVoucher | InferenceVoucher): Promise<void>;
+    /** Logs a refusal instead of throwing: nothing waits on capture or release. Throws only if the operator can't be reached. */
+    private settle;
 }
 //# sourceMappingURL=operatorClient.d.ts.map

package/dist/client/operatorClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,0BAA0B,CAAC;AAEpF,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;CACJ;AAED,gHAAgH;AAChH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE;QACL,IAAI,EAAE,WAAW,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,kCAAkC,EAAE,MAAM,CAAC;QAC3C,mCAAmC,EAAE,MAAM,CAAC;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;IACD,KAAK,EAAE;QACH,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACxB,CAAA;CACJ;AAED,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAmBhD,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAhC,YAA6B,GAAG,EAAE,MAAM,GAAG,SAAS,EAAI;IAExD;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B7D;CACJ"}
+{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"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"}

package/dist/client/operatorClient.js

@@ -1,62 +1,146 @@
-export const SETTLE_PAYMENT_MAX_RETRIES = 5;
-export const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
+import { operatorAuthorization } from "./operatorAuth.js";
+export const OPERATOR_MAX_RETRIES = 5;
+/** Authorization runs while the caller waits, so it gives up much sooner than capture and release. */
+export const AUTHORIZE_MAX_RETRIES = 2;
+export const OPERATOR_BASE_DELAY_MS = 1000;
+export const AUTHORIZE_BASE_DELAY_MS = 200;
 /** Per attempt. A timed-out attempt is retried like a network error. */
-export const SETTLE_PAYMENT_TIMEOUT_MS = 10_000;
+export const OPERATOR_TIMEOUT_MS = 10_000;
 /**
- * Transient failures. Resending is safe even if an earlier attempt reached the operator: it stores a
- * unique receipt per (requestId, invocationId), so a repeat is rejected with 409.
- * Rejections (400, 401, 404, 409, 422) are not retried because they won't change.
+ * Transient failures. Resending is safe even if an earlier attempt reached the operator: every payment
+ * request is idempotent per voucher (requestId, invocationId).
+ * Rejections (400, 401, 402, 403, 404, 409, 422) are not retried because they won't change.
  */
 const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
 /**
- * Delay before retry `attempt` (0-based): exponential backoff (1s, 2s, 4s, 8s, 16s),
+ * Delay before retry `attempt` (0-based): exponential backoff from `baseDelayMs`,
  * or the operator's `Retry-After` seconds when that is longer.
  */
-function retryDelayMs(response, attempt) {
-    const backoff = SETTLE_PAYMENT_BASE_DELAY_MS * 2 ** attempt;
+function retryDelayMs(response, attempt, baseDelayMs) {
+    const backoff = baseDelayMs * 2 ** attempt;
     const retryAfterSeconds = Number(response?.headers.get('retry-after') ?? NaN);
     return Number.isFinite(retryAfterSeconds) ? Math.max(backoff, retryAfterSeconds * 1000) : backoff;
 }
+async function errorMessage(response) {
+    const body = await response.json().catch(() => undefined);
+    return typeof body?.error === 'string' ? body.error : `${response.status} ${response.statusText}`.trim();
+}
+/** Talks to the operator as this node. Every request is signed with the node's key. */
 export class OperatorClient {
     url;
-    constructor(url) {
+    publicKey;
+    privateKey;
+    constructor(url, publicKey, privateKey) {
         this.url = url;
+        this.publicKey = publicKey;
+        this.privateKey = privateKey;
     }
     /**
-     * Retries `RETRYABLE_STATUSES` and network errors up to `SETTLE_PAYMENT_MAX_RETRIES` times.
+     * POSTs `body`, retrying `RETRYABLE_STATUSES` and network errors up to `retries` times.
+     * Each attempt is signed afresh, since the operator only accepts recent timestamps.
      * Throws the last network error if the operator could not be reached, or if no operator URL is configured.
      */
-    async settlePayment(payment) {
+    async post(path, body, retries, baseDelayMs) {
         if (!this.url) {
-            throw new Error('Cannot settle payment: no operator URL is configured');
+            throw new Error('No operator URL is configured');
         }
-        const body = JSON.stringify(payment);
-        let response;
+        const url = `${this.url}${path}`;
+        const serialized = JSON.stringify(body);
         for (let attempt = 0;; attempt++) {
             let retryable;
             try {
-                response = await fetch(`${this.url}/payment`, {
+                const response = await fetch(url, {
                     method: 'POST',
-                    body,
+                    body: serialized,
                     headers: {
                         'Content-Type': 'application/json',
+                        Authorization: operatorAuthorization('POST', url, body, this.publicKey, this.privateKey),
                     },
-                    signal: AbortSignal.timeout(SETTLE_PAYMENT_TIMEOUT_MS),
+                    signal: AbortSignal.timeout(OPERATOR_TIMEOUT_MS),
                 });
-                if (!RETRYABLE_STATUSES.has(response.status) || attempt >= SETTLE_PAYMENT_MAX_RETRIES) {
-                    break;
+                if (!RETRYABLE_STATUSES.has(response.status) || attempt >= retries) {
+                    return response;
                 }
                 retryable = response;
             }
             catch (error) {
-                if (attempt >= SETTLE_PAYMENT_MAX_RETRIES) {
+                if (attempt >= retries) {
                     throw error;
                 }
             }
-            await new Promise(resolve => setTimeout(resolve, retryDelayMs(retryable, attempt)));
+            await new Promise(resolve => setTimeout(resolve, retryDelayMs(retryable, attempt, baseDelayMs)));
+        }
+    }
+    /**
+     * Returns the organization this node is enrolled in. With an `enrollmentToken` from the dashboard,
+     * enrolls the node first; a node that is already enrolled ignores the token. Throws if the node is
+     * not enrolled or the operator refuses.
+     */
+    async session(enrollmentToken, baseUrl) {
+        const body = { ...(enrollmentToken ? { enrollmentToken } : {}), ...(baseUrl ? { baseUrl } : {}) };
+        const response = await this.post('/nodes/session', body, OPERATOR_MAX_RETRIES, OPERATOR_BASE_DELAY_MS);
+        if (!response.ok) {
+            throw new Error(`Operator refused this node's session: ${await errorMessage(response)}`);
         }
+        return await response.json();
+    }
+    /**
+     * Asks the operator to hold the voucher's amount (or `maxAmount`) on the payer's balance, before
+     * running the paid function. An unreachable operator is reported as a 503 refusal.
+     */
+    async authorize(voucher) {
+        const result = await this.hold('/payments/authorize', { voucher });
+        return result.ok ? { ok: true } : result;
+    }
+    /**
+     * Asks the operator to hold a script run's cost on the paying API client's organization, before running
+     * it. An unreachable operator is reported as a 503 refusal.
+     */
+    async authorizeRun(request) {
+        const result = await this.hold('/runs/authorize', request);
+        if (!result.ok)
+            return result;
+        const { heldMicroUsd, maxTokens } = result.body;
+        return { ok: true, heldMicroUsd, maxTokens };
+    }
+    /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
+    async captureRun(request) {
+        await this.settle('/runs/capture', request);
+    }
+    /** Releases a held run without charging it, for a script this node failed to run. */
+    async releaseRun(request) {
+        await this.settle('/runs/release', request);
+    }
+    /** Authorization runs while the caller waits, so it retries briefly and reports an unreachable operator as 503. */
+    async hold(path, body) {
+        let response;
+        try {
+            response = await this.post(path, body, AUTHORIZE_MAX_RETRIES, AUTHORIZE_BASE_DELAY_MS);
+        }
+        catch (error) {
+            console.error(`Failed to reach the operator for ${path}`, error);
+            return { ok: false, status: 503, error: 'Payment operator is unavailable' };
+        }
+        if (response.ok) {
+            return { ok: true, body: await response.json().catch(() => undefined) };
+        }
+        // Retries ran out on a transient failure: the caller may try again later.
+        const status = RETRYABLE_STATUSES.has(response.status) ? 503 : response.status;
+        return { ok: false, status, error: await errorMessage(response) };
+    }
+    /** Charges a held voucher: its amount, or for inference the reported usage capped at the hold. */
+    async capture(payment) {
+        await this.settle('/payments/capture', payment);
+    }
+    /** Releases a held voucher without charging it, for a call that failed or cost nothing. */
+    async release(voucher) {
+        await this.settle('/payments/release', { voucher });
+    }
+    /** Logs a refusal instead of throwing: nothing waits on capture or release. Throws only if the operator can't be reached. */
+    async settle(path, body) {
+        const response = await this.post(path, body, OPERATOR_MAX_RETRIES, OPERATOR_BASE_DELAY_MS);
         if (!response.ok) {
-            console.error(`Failed to settle payment: ${response.statusText} body: ${await response.text()}`);
+            console.error(`Operator refused ${path}: ${await errorMessage(response)}`);
         }
     }
 }

package/dist/client/runTokens.d.ts

@@ -0,0 +1,23 @@
+import { type JWTVerifyGetKey } from "jose";
+/** The `iss` of every run token. Copied from RUN_TOKEN_ISSUER in apps/operator/src/runs/tokens.ts. */
+export declare const RUN_TOKEN_ISSUER = "stellarium";
+/** Who a run token lets run scripts on this node, and which organization pays. */
+export interface RunTokenClaims {
+    clientId: string;
+    organizationId: string;
+}
+/** Whether `token` has the three base64url segments of a JWT, as opposed to an API key. */
+export declare function looksLikeJwt(token: string): boolean;
+/**
+ * Verifies the run tokens API clients get from the operator's `POST /v1/oauth/token`, against the
+ * operator's published keys. A token is only valid at the node whose public key is its audience.
+ */
+export declare class RunTokenVerifier {
+    private readonly nodePublicKey;
+    private readonly keys;
+    /** `keys` replaces fetching `{operatorUrl}/.well-known/jwks.json`, in tests. */
+    constructor(operatorUrl: string, nodePublicKey: string, keys?: JWTVerifyGetKey);
+    /** The token's claims, or undefined unless it is signed by the operator, unexpired and addressed to this node. */
+    verify(token: string): Promise<RunTokenClaims | undefined>;
+}
+//# sourceMappingURL=runTokens.d.ts.map

package/dist/client/runTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTokens.d.ts","sourceRoot":"","sources":["../../src/client/runTokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,eAAe,EAAa,MAAM,MAAM,CAAC;AAE3E,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAIQ,OAAO,CAAC,QAAQ,CAAC,aAAa;IAH/D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IAEvC,gFAAgF;IAChF,YAAY,WAAW,EAAE,MAAM,EAAmB,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,EAG9F;IAED,kHAAkH;IAC5G,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAU/D;CACJ"}

package/dist/client/runTokens.js

@@ -0,0 +1,34 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+/** The `iss` of every run token. Copied from RUN_TOKEN_ISSUER in apps/operator/src/runs/tokens.ts. */
+export const RUN_TOKEN_ISSUER = 'stellarium';
+/** Whether `token` has the three base64url segments of a JWT, as opposed to an API key. */
+export function looksLikeJwt(token) {
+    return /^[\w-]+\.[\w-]+\.[\w-]+$/.test(token);
+}
+/**
+ * Verifies the run tokens API clients get from the operator's `POST /v1/oauth/token`, against the
+ * operator's published keys. A token is only valid at the node whose public key is its audience.
+ */
+export class RunTokenVerifier {
+    nodePublicKey;
+    keys;
+    /** `keys` replaces fetching `{operatorUrl}/.well-known/jwks.json`, in tests. */
+    constructor(operatorUrl, nodePublicKey, keys) {
+        this.nodePublicKey = nodePublicKey;
+        // Cached, and refetched when a token names a key it doesn't have.
+        this.keys = keys ?? createRemoteJWKSet(new URL(`${operatorUrl}/.well-known/jwks.json`));
+    }
+    /** The token's claims, or undefined unless it is signed by the operator, unexpired and addressed to this node. */
+    async verify(token) {
+        try {
+            const { payload } = await jwtVerify(token, this.keys, { issuer: RUN_TOKEN_ISSUER, audience: this.nodePublicKey, algorithms: ['EdDSA'] });
+            if (typeof payload.sub !== 'string' || typeof payload.org !== 'string') {
+                return undefined;
+            }
+            return { clientId: payload.sub, organizationId: payload.org };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/db/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE7C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAY1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA8I9C"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE7C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAc1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA+I9C"}

package/dist/db/db.js

@@ -8,8 +8,10 @@ export const DEFAULT_DATABASE_PATH = './requestscript.db';
  * Version 3 added `resource.website` and the `description` columns of the resource tables.
  * Version 4 renamed `resource_function_payment_manifest.cost_lamports` to `cost_micro_usdc` (payments moved to USDC).
  * Version 5 added `resource_function.kind` and per-token inference pricing, which made `cost_micro_usdc` nullable.
+ * Version 6 moved payments to Stripe: `*_micro_usdc` columns became `*_micro_usd`, and `recipient_address`
+ * became `recipient_organization_id`.
  */
-const SCHEMA_VERSION = 5;
+const SCHEMA_VERSION = 6;
 /** Opens (or creates) the node database and brings its schema up to date. Pass ':memory:' for tests. */
 export async function openDatabase(filename = DEFAULT_DATABASE_PATH) {
     const db = await open({ filename, driver: sqlite3.Database });
@@ -92,10 +94,11 @@ export async function createTables(db) {
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             resource_function_id INTEGER NOT NULL,
             -- Null for inference functions, which are priced per million tokens instead.
-            cost_micro_usdc INTEGER,
-            input_cost_micro_usdc_per_million_tokens INTEGER,
-            output_cost_micro_usdc_per_million_tokens INTEGER,
-            recipient_address TEXT NOT NULL,
+            cost_micro_usd INTEGER,
+            input_cost_micro_usd_per_million_tokens INTEGER,
+            output_cost_micro_usd_per_million_tokens INTEGER,
+            -- The hosting node's organization. Null only if a peer advertised the manifest without one.
+            recipient_organization_id TEXT,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { StellariumNode, resolveConfig, type StellariumNodeOptions } from './server.js';
 export type { NodeConfig } from './service.js';
 export type { StellariumFixedPaymentManifest, StellariumInferencePaymentManifest, StellariumResource, StellariumResourceFunction, StellariumResourceFunctionKind, StellariumResourceFunctionParameter, StellariumResourceFunctionPaymentManifest, } from './resource/repository.js';
-export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, type InferenceEstimate, type InferencePaymentVoucher, type PaymentVoucher, } from './resource/invoker.js';
+export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, type RunContext, type InferenceEstimate, type InferencePaymentVoucher, type PaymentVoucher, } from './resource/invoker.js';
 export { inferenceCharge, MAX_TOKENS_PARAMETER, type InferenceResult, type InferenceUsage } from './resource/inference.js';
-export type { InferencePaymentSubmission, PaymentSubmission } from './client/operatorClient.js';
+export type { FixedPaymentVoucher, InferencePaymentSubmission, InferenceVoucher, PaymentSubmission, RunAuthorizationRequest } from './client/operatorClient.js';
+export { RUN_TOKEN_ISSUER, RunTokenVerifier, type RunTokenClaims } from './client/runTokens.js';
+export { OPERATOR_AUTH_SCHEME, operatorAuthorization, operatorRequestPayload } from './client/operatorAuth.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';

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,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACR,8BAA8B,EAC9B,kCAAkC,EAClC,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,mCAAmC,EACnC,yCAAyC,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACH,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC3H,YAAY,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEhG,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"}
+{"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,EACR,8BAA8B,EAC9B,kCAAkC,EAClC,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,mCAAmC,EACnC,yCAAyC,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACH,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC3H,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAEhK,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE/G,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

@@ -2,5 +2,9 @@ export { StellariumNode, resolveConfig } from './server.js';
 // The voucher wire format, so the operator and other settlers can test against the real signer.
 export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, } from './resource/invoker.js';
 export { inferenceCharge, MAX_TOKENS_PARAMETER } from './resource/inference.js';
+// Run token verification, so the operator can test its tokens against the real verifier.
+export { RUN_TOKEN_ISSUER, RunTokenVerifier } from './client/runTokens.js';
+// The operator request signature, so the operator can test against the real signer.
+export { OPERATOR_AUTH_SCHEME, operatorAuthorization, operatorRequestPayload } from './client/operatorAuth.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/resource/inference.d.ts

@@ -14,19 +14,21 @@ export interface InferenceResult {
 }
 /** The per-million-token rates a charge is computed from. */
 export interface InferenceRates {
-    inputCostMicroUsdcPerMillionTokens: number;
-    outputCostMicroUsdcPerMillionTokens: number;
+    inputCostMicroUsdPerMillionTokens: number;
+    outputCostMicroUsdPerMillionTokens: number;
 }
 export declare function isInferenceManifest(manifest: StellariumResourceFunctionPaymentManifest | undefined): manifest is StellariumInferencePaymentManifest;
 export declare function isInferenceFunction(fn: Pick<StellariumResourceFunction, 'kind'>): boolean;
 /**
- * Micro-USDC owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
+ * Micro-USD owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
  * Computed exactly in BigInt. Throws if the charge isn't a safe integer.
  * The operator keeps a copy (apps/operator/src/inference.ts) that must stay in sync.
  */
 export declare function inferenceCharge(rates: InferenceRates, inputTokens: number, outputTokens: number): number;
 /** The call's `maxTokens` value, or undefined unless it is a positive int32. */
 export declare function parseMaxTokens(parameters: ResourceFunctionCallParameter[]): number | undefined;
+/** The function's own input-token estimate, or undefined if its estimator failed or returned something other than a count. */
+export declare function estimateInputTokens(fn: StellariumResourceFunction, parameters: ResourceFunctionCallParameter[]): Promise<number | undefined>;
 /** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
 export declare function parseInferenceResult(result: unknown): InferenceResult | undefined;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/resource/inference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,kCAAkC,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAC;AAEjJ,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC3B,kCAAkC,EAAE,MAAM,CAAC;IAC3C,mCAAmC,EAAE,MAAM,CAAC;CAC/C;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yCAAyC,GAAG,SAAS,GAAG,QAAQ,IAAI,kCAAkC,CAEnJ;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzF;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxG;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAajF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAsB9E"}
+{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/resource/inference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,kCAAkC,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAC;AAEjJ,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC3B,iCAAiC,EAAE,MAAM,CAAC;IAC1C,kCAAkC,EAAE,MAAM,CAAC;CAC9C;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yCAAyC,GAAG,SAAS,GAAG,QAAQ,IAAI,kCAAkC,CAEnJ;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzF;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxG;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED,8HAA8H;AAC9H,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,0BAA0B,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAOlJ;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAajF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAsB9E"}

package/dist/resource/inference.js

@@ -2,7 +2,7 @@
 export const MAX_TOKENS_PARAMETER = 'maxTokens';
 const INT32_MAX = 2_147_483_647;
 export function isInferenceManifest(manifest) {
-    return typeof manifest === 'object' && manifest !== null && 'inputCostMicroUsdcPerMillionTokens' in manifest;
+    return typeof manifest === 'object' && manifest !== null && 'inputCostMicroUsdPerMillionTokens' in manifest;
 }
 export function isInferenceFunction(fn) {
     return fn.kind === 'inference';
@@ -11,13 +11,13 @@ function isNonnegativeSafeInteger(value) {
     return Number.isSafeInteger(value) && value >= 0;
 }
 /**
- * Micro-USDC owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
+ * Micro-USD owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
  * Computed exactly in BigInt. Throws if the charge isn't a safe integer.
  * The operator keeps a copy (apps/operator/src/inference.ts) that must stay in sync.
  */
 export function inferenceCharge(rates, inputTokens, outputTokens) {
-    const micros = BigInt(inputTokens) * BigInt(rates.inputCostMicroUsdcPerMillionTokens)
-        + BigInt(outputTokens) * BigInt(rates.outputCostMicroUsdcPerMillionTokens);
+    const micros = BigInt(inputTokens) * BigInt(rates.inputCostMicroUsdPerMillionTokens)
+        + BigInt(outputTokens) * BigInt(rates.outputCostMicroUsdPerMillionTokens);
     const charge = (micros + 999999n) / 1000000n;
     if (charge > BigInt(Number.MAX_SAFE_INTEGER)) {
         throw new Error('Inference charge exceeds the largest safe integer');
@@ -29,6 +29,16 @@ export function parseMaxTokens(parameters) {
     const value = parameters.find(parameter => parameter.name === MAX_TOKENS_PARAMETER)?.value;
     return Number.isInteger(value) && value > 0 && value <= INT32_MAX ? value : undefined;
 }
+/** The function's own input-token estimate, or undefined if its estimator failed or returned something other than a count. */
+export async function estimateInputTokens(fn, parameters) {
+    try {
+        const inputTokens = await fn.estimateInputTokens?.(parameters);
+        return Number.isSafeInteger(inputTokens) && inputTokens >= 0 ? inputTokens : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
 export function parseInferenceResult(result) {
     if (typeof result !== 'object' || result === null || !('usage' in result)) {
@@ -64,9 +74,9 @@ export function validateInferenceFunction(fn) {
         return;
     }
     if (!isInferenceManifest(fn.paymentManifest)
-        || !isNonnegativeSafeInteger(fn.paymentManifest.inputCostMicroUsdcPerMillionTokens)
-        || !isNonnegativeSafeInteger(fn.paymentManifest.outputCostMicroUsdcPerMillionTokens)) {
-        throw new Error(`Inference function ${fn.name} must price input and output tokens as nonnegative integer micro-USDC per million tokens`);
+        || !isNonnegativeSafeInteger(fn.paymentManifest.inputCostMicroUsdPerMillionTokens)
+        || !isNonnegativeSafeInteger(fn.paymentManifest.outputCostMicroUsdPerMillionTokens)) {
+        throw new Error(`Inference function ${fn.name} must price input and output tokens as nonnegative integer micro-USD per million tokens`);
     }
     if (typeof fn.estimateInputTokens !== 'function') {
         throw new Error(`Paid inference function ${fn.name} must declare estimateInputTokens`);