stellarium-ts 0.12.0 → 0.14.0

package/dist/client/operatorClient.d.ts

@@ -6,15 +6,21 @@ export interface PaymentSubmission {
         recipientAddress: string;
         signature: string;
         expiresAt: string;
+        invocationHash: string;
         publicKey: string;
     };
-    resourcePath: string;
-    resourceName: string;
-    parameters: unknown[];
 }
+export declare const SETTLE_PAYMENT_MAX_RETRIES = 5;
+export declare const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
+/** Per attempt. A timed-out attempt is retried like a network error. */
+export declare const SETTLE_PAYMENT_TIMEOUT_MS = 10000;
 export declare class OperatorClient {
     private readonly url;
-    constructor(url: string);
+    constructor(url: string | undefined);
+    /**
+     * Retries `RETRYABLE_STATUSES` and network errors up to `SETTLE_PAYMENT_MAX_RETRIES` times.
+     * Throws the last network error if the operator could not be reached, or if no operator URL is configured.
+     */
     settlePayment(payment: PaymentSubmission): Promise<void>;
 }
 //# 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":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,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,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;IAED,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAhC,YAA6B,GAAG,EAAE,MAAM,EAAI;IAEtC,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW7D;CACJ"}
+{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,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,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"}

package/dist/client/operatorClient.js

@@ -1,16 +1,60 @@
+export const SETTLE_PAYMENT_MAX_RETRIES = 5;
+export const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
+/** Per attempt. A timed-out attempt is retried like a network error. */
+export const SETTLE_PAYMENT_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) before paying, so a repeat is rejected with 409.
+ * Rejections (400, 401, 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),
+ * or the operator's `Retry-After` seconds when that is longer.
+ */
+function retryDelayMs(response, attempt) {
+    const backoff = SETTLE_PAYMENT_BASE_DELAY_MS * 2 ** attempt;
+    const retryAfterSeconds = Number(response?.headers.get('retry-after') ?? NaN);
+    return Number.isFinite(retryAfterSeconds) ? Math.max(backoff, retryAfterSeconds * 1000) : backoff;
+}
 export class OperatorClient {
     url;
     constructor(url) {
         this.url = url;
     }
+    /**
+     * Retries `RETRYABLE_STATUSES` and network errors up to `SETTLE_PAYMENT_MAX_RETRIES` times.
+     * Throws the last network error if the operator could not be reached, or if no operator URL is configured.
+     */
     async settlePayment(payment) {
-        const response = await fetch(`${this.url}/payment`, {
-            method: 'POST',
-            body: JSON.stringify(payment),
-            headers: {
-                'Content-Type': 'application/json',
-            },
-        });
+        if (!this.url) {
+            throw new Error('Cannot settle payment: no operator URL is configured');
+        }
+        const body = JSON.stringify(payment);
+        let response;
+        for (let attempt = 0;; attempt++) {
+            let retryable;
+            try {
+                response = await fetch(`${this.url}/payment`, {
+                    method: 'POST',
+                    body,
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    signal: AbortSignal.timeout(SETTLE_PAYMENT_TIMEOUT_MS),
+                });
+                if (!RETRYABLE_STATUSES.has(response.status) || attempt >= SETTLE_PAYMENT_MAX_RETRIES) {
+                    break;
+                }
+                retryable = response;
+            }
+            catch (error) {
+                if (attempt >= SETTLE_PAYMENT_MAX_RETRIES) {
+                    throw error;
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, retryDelayMs(retryable, attempt)));
+        }
         if (!response.ok) {
             console.error(`Failed to settle payment: ${response.statusText} body: ${await response.text()}`);
         }

package/dist/crypto/utils.d.ts

@@ -1,3 +1,12 @@
 export declare function signData(data: Object, privateKey: string): string;
+export declare function hashData(data: Object): string;
 export declare function verifyData(data: Object, publicKey: string, signature: string): boolean;
+/** Longest lifetime accepted for a signed peer or resource broadcast, so a captured one can't be replayed indefinitely. */
+export declare const MAX_SIGNATURE_LIFETIME_MS: number;
+/** True when `expiry` is a valid date in the future, no more than `maxLifetimeMs` away. */
+export declare function isFreshExpiry(expiry: string, maxLifetimeMs?: number): boolean;
+/** True when `publicKey` is an Ed25519 SPKI DER key in base64url, the form nodes sign with. */
+export declare function isValidPublicKey(publicKey: string): boolean;
+/** verifyData that treats a malformed key or signature as an invalid signature instead of throwing. */
+export declare function safeVerifyData(data: Object, publicKey: string, signature: string): boolean;
 //# sourceMappingURL=utils.d.ts.map

package/dist/crypto/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/crypto/utils.ts"],"names":[],"mappings":"AASA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQtF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/crypto/utils.ts"],"names":[],"mappings":"AASA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAQtF;AAED,2HAA2H;AAC3H,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AAExD,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,GAAE,MAAkC,GAAG,OAAO,CAIxG;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAM3D;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAM1F"}

package/dist/crypto/utils.js

@@ -1,4 +1,4 @@
-import { createPrivateKey, createPublicKey, sign, verify, } from "node:crypto";
+import { createHash, createPrivateKey, createPublicKey, sign, verify, } from "node:crypto";
 export function signData(data, privateKey) {
     const key = createPrivateKey({
         key: Buffer.from(privateKey, "base64url"),
@@ -8,6 +8,9 @@ export function signData(data, privateKey) {
     const bytes = Buffer.from(JSON.stringify(data));
     return sign(null, bytes, key).toString('base64url');
 }
+export function hashData(data) {
+    return createHash('sha256').update(JSON.stringify(data)).digest('base64url');
+}
 export function verifyData(data, publicKey, signature) {
     const key = createPublicKey({
         key: Buffer.from(publicKey, "base64url"),
@@ -17,3 +20,29 @@ export function verifyData(data, publicKey, signature) {
     const bytes = Buffer.from(JSON.stringify(data));
     return verify(null, bytes, key, Buffer.from(signature, 'base64url'));
 }
+/** Longest lifetime accepted for a signed peer or resource broadcast, so a captured one can't be replayed indefinitely. */
+export const MAX_SIGNATURE_LIFETIME_MS = 1000 * 60 * 60;
+/** True when `expiry` is a valid date in the future, no more than `maxLifetimeMs` away. */
+export function isFreshExpiry(expiry, maxLifetimeMs = MAX_SIGNATURE_LIFETIME_MS) {
+    const expiresAt = Date.parse(expiry);
+    const now = Date.now();
+    return Number.isFinite(expiresAt) && expiresAt > now && expiresAt <= now + maxLifetimeMs;
+}
+/** True when `publicKey` is an Ed25519 SPKI DER key in base64url, the form nodes sign with. */
+export function isValidPublicKey(publicKey) {
+    try {
+        return createPublicKey({ key: Buffer.from(publicKey, "base64url"), format: "der", type: "spki" }).asymmetricKeyType === "ed25519";
+    }
+    catch {
+        return false;
+    }
+}
+/** verifyData that treats a malformed key or signature as an invalid signature instead of throwing. */
+export function safeVerifyData(data, publicKey, signature) {
+    try {
+        return verifyData(data, publicKey, signature);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/db/db.d.ts

@@ -1,5 +1,6 @@
-import sqlite3 from 'sqlite3';
-declare const db: import("sqlite").Database<sqlite3.Database, sqlite3.Statement>;
-export declare function createTables(): Promise<void>;
-export default db;
+import { type Database } from 'sqlite';
+export declare const DEFAULT_DATABASE_PATH = "./requestscript.db";
+/** Opens (or creates) the node database and brings its schema up to date. Pass ':memory:' for tests. */
+export declare function openDatabase(filename?: string): Promise<Database>;
+export declare function createTables(db: Database): Promise<void>;
 //# sourceMappingURL=db.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,QAAA,MAAM,EAAE,gEAGN,CAAC;AAIH,wBAAsB,YAAY,kBA+DjC;eAGc,EAAE"}
+{"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;AAU1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA0I9C"}

package/dist/db/db.js

@@ -1,11 +1,31 @@
 import sqlite3 from 'sqlite3';
 import { open } from 'sqlite';
-const db = await open({
-    filename: './requestscript.db', // Specify the database file
-    driver: sqlite3.Database,
-});
-// Create tables
-export async function createTables() {
+export const DEFAULT_DATABASE_PATH = './requestscript.db';
+/**
+ * Bumped whenever the schema changes in a way `CREATE TABLE IF NOT EXISTS` can't apply.
+ * Version 1 dropped `UNIQUE (base_url)` from `resource` and added uniqueness to the function tables.
+ * Version 2 added `resource_function.restricted`.
+ * Version 3 added `resource.website` and the `description` columns of the resource tables.
+ */
+const SCHEMA_VERSION = 3;
+/** 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 });
+    await createTables(db);
+    return db;
+}
+export async function createTables(db) {
+    const { user_version: version } = await db.get('PRAGMA user_version') ?? { user_version: 0 };
+    if (version < SCHEMA_VERSION) {
+        // Resource rows are a cache of what peers advertise, and are relearned on the next broadcast.
+        // SQLite can't drop a constraint in place, so rebuild them. Peers are kept.
+        await db.exec(`
+            DROP TABLE IF EXISTS resource_function_payment_manifest;
+            DROP TABLE IF EXISTS resource_function_parameter;
+            DROP TABLE IF EXISTS resource_function;
+            DROP TABLE IF EXISTS resource;
+        `);
+    }
     await db.exec(`
         CREATE TABLE IF NOT EXISTS peer (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -26,13 +46,14 @@ export async function createTables() {
             path TEXT NOT NULL,
             name TEXT NOT NULL,
             base_url TEXT NOT NULL,
+            website TEXT,
+            description TEXT,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 
             FOREIGN KEY (peer_id) REFERENCES peer(id),
 
-            UNIQUE (path, name),
-            UNIQUE (base_url)
+            UNIQUE (path, name)
         );
 
         CREATE TABLE IF NOT EXISTS resource_function (
@@ -40,10 +61,14 @@ export async function createTables() {
             resource_id INTEGER NOT NULL,
             name TEXT NOT NULL,
             return_type TEXT NOT NULL,
+            description TEXT,
+            restricted INTEGER NOT NULL DEFAULT 0,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 
-            FOREIGN KEY (resource_id) REFERENCES resource(id)
+            FOREIGN KEY (resource_id) REFERENCES resource(id),
+
+            UNIQUE (resource_id, name)
         );
 
         CREATE TABLE IF NOT EXISTS resource_function_parameter (
@@ -51,10 +76,13 @@ export async function createTables() {
             resource_function_id INTEGER NOT NULL,
             name TEXT NOT NULL,
             parameter_type TEXT NOT NULL,
+            description TEXT,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 
-            FOREIGN KEY (resource_function_id) REFERENCES resource_function(id)
+            FOREIGN KEY (resource_function_id) REFERENCES resource_function(id),
+
+            UNIQUE (resource_function_id, name)
         );
 
         CREATE TABLE IF NOT EXISTS resource_function_payment_manifest (
@@ -65,8 +93,61 @@ export async function createTables() {
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 
-            FOREIGN KEY (resource_function_id) REFERENCES resource_function(id)
+            FOREIGN KEY (resource_function_id) REFERENCES resource_function(id),
+
+            UNIQUE (resource_function_id)
+        );
+
+        -- Grants this node signed, kept so their audience can renew them.
+        -- A delegated grant's parent_grant_issuer and parent_grant_id name the held grant it narrows.
+        CREATE TABLE IF NOT EXISTS issued_grant (
+            id TEXT PRIMARY KEY,
+            audience TEXT NOT NULL,
+            capabilities TEXT NOT NULL,
+            parent_grant_issuer TEXT,
+            parent_grant_id TEXT,
+            lifetime_ms INTEGER NOT NULL,
+            renewable_until TEXT,
+            created_at TEXT NOT NULL
+        );
+
+        -- Chains whose leaf grant names this node as its audience, keyed by the leaf's issuer and id.
+        -- Issuers choose their own ids, so an id alone doesn't identify a grant.
+        CREATE TABLE IF NOT EXISTS held_grant (
+            issuer TEXT NOT NULL,
+            id TEXT NOT NULL,
+            root_issuer_base_url TEXT NOT NULL,
+            chain TEXT NOT NULL,
+            issued_at TEXT NOT NULL,
+            expires_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+
+            PRIMARY KEY (issuer, id)
+        );
+        CREATE INDEX IF NOT EXISTS held_grant_root ON held_grant (root_issuer_base_url, expires_at);
+
+        -- Keyed like held grants, so revoking one issuer's grant leaves another's with the same id alone.
+        CREATE TABLE IF NOT EXISTS revoked_grant (
+            issuer TEXT NOT NULL,
+            grant_id TEXT NOT NULL,
+            revoked_at TEXT NOT NULL,
+
+            PRIMARY KEY (issuer, grant_id)
+        );
+
+        -- publicKey:nonce of accepted authorizations and grant requests, until they expire.
+        CREATE TABLE IF NOT EXISTS seen_nonce (
+            key TEXT PRIMARY KEY,
+            expires_at INTEGER NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS seen_nonce_expires_at ON seen_nonce (expires_at);
+
+        -- Keys an admin blocked from calling this node or getting grants from it.
+        CREATE TABLE IF NOT EXISTS blocked_caller (
+            public_key TEXT PRIMARY KEY,
+            reason TEXT,
+            blocked_at TEXT NOT NULL
         );
     `);
+    await db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
 }
-export default db;

package/dist/grant/grant.d.ts

@@ -0,0 +1,132 @@
+import type { ResourceFunctionCallParameter } from "requestscript";
+/**
+ * What a grant lets its audience call. `resourcePath` is exact, a segment prefix such as
+ * `com.example.*`, or `*` for any path. An omitted `resourceName` or `functionName` matches any.
+ * Each constraint requires the parameter of that name to equal the value (compared as JSON).
+ */
+export interface Capability {
+    resourcePath: string;
+    resourceName?: string;
+    functionName?: string;
+    constraints?: Record<string, unknown>;
+}
+/**
+ * A signed statement that `issuer` lets `audience` call `capabilities` until `expiresAt`.
+ * A root grant (`parent: null`) is issued by the provider. A delegated grant is issued by the
+ * previous grant's audience, may only narrow it, and names it by `grantHash`.
+ */
+export interface Grant {
+    /** Kept across renewals, so revoking an id revokes every renewal of it. */
+    id: string;
+    /** Ed25519 SPKI DER, base64url. */
+    issuer: string;
+    /** Where the audience renews this grant. */
+    issuerBaseUrl: string;
+    audience: string;
+    capabilities: Capability[];
+    issuedAt: string;
+    expiresAt: string;
+    parent: string | null;
+    signature: string;
+}
+/** Sent with a call to a restricted function. Signed by the leaf grant's audience. */
+export interface InvocationAuthorization {
+    publicKey: string;
+    /** Root first. */
+    grants: Grant[];
+    nonce: string;
+    expiresAt: string;
+    signature: string;
+}
+/** Asks a grant's issuer for a fresh copy of it. Signed by the grant's audience. */
+export interface GrantRenewalRequest {
+    grantId: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: string;
+    signature: string;
+}
+/** Asks a node for a new root grant. Signed by the key that would become its audience. */
+export interface GrantRequest {
+    publicKey: string;
+    capabilities: Capability[];
+    /** Anything the node's approval hook needs, such as an invite code. */
+    details?: Record<string, unknown> | null;
+    nonce: string;
+    expiresAt: string;
+    signature: string;
+}
+/** Longest lifetime of one grant. Renewal extends access past it. */
+export declare const MAX_GRANT_LIFETIME_MS: number;
+/** Longest lifetime of an invocation authorization or a renewal request. */
+export declare const MAX_AUTHORIZATION_LIFETIME_MS: number;
+/** Longest delegation chain, root included. */
+export declare const MAX_GRANT_CHAIN_LENGTH = 4;
+/**
+ * How far ahead of the verifier's clock a signer's clock may run. Signers use the full lifetimes
+ * above, so verifiers accept expiries up to this much past them.
+ */
+export declare const CLOCK_SKEW_TOLERANCE_MS: number;
+/** The object a grant's signature covers: every field except `signature`. Key order is part of the signed bytes. */
+export declare function grantPayload(grant: Omit<Grant, "signature">): {
+    id: string;
+    issuer: string;
+    issuerBaseUrl: string;
+    audience: string;
+    capabilities: Capability[];
+    issuedAt: string;
+    expiresAt: string;
+    parent: string | null;
+};
+/** Names a grant as a delegated grant's `parent`. Independent of the key order the grant arrived in. */
+export declare function grantHash(grant: Grant): string;
+/** Key order is part of the signed bytes. */
+export declare function invocationAuthorizationPayload(payload: {
+    invocationHash: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: string;
+    grantsHash: string;
+}): {
+    invocationHash: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: string;
+    grantsHash: string;
+};
+export declare function grantsHash(grants: Grant[]): string;
+/** Key order is part of the signed bytes. */
+export declare function grantRenewalPayload(request: Omit<GrantRenewalRequest, "signature">): {
+    grantId: string;
+    publicKey: string;
+    nonce: string;
+    expiresAt: string;
+};
+/** Key order is part of the signed bytes. Omitted `details` are signed as null. */
+export declare function grantRequestPayload(request: Omit<GrantRequest, "signature">): {
+    publicKey: string;
+    capabilities: Capability[];
+    details: Record<string, unknown> | null;
+    nonce: string;
+    expiresAt: string;
+};
+export declare function signGrant(grant: Omit<Grant, "signature">, privateKey: string): Grant;
+export declare function isCapability(value: unknown): value is Capability;
+export declare function isGrant(value: unknown): value is Grant;
+export declare function isAuthorization(value: unknown): value is InvocationAuthorization;
+export declare function capabilityMatches(capability: Capability, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): boolean;
+/** True when `child` allows nothing `parent` doesn't. A delegated grant may only narrow its parent. */
+export declare function capabilityCovers(parent: Capability, child: Capability): boolean;
+export type ChainResult = {
+    ok: true;
+    leaf: Grant;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Checks a chain's signatures, expiries and links, root first. Revocation is the caller's
+ * job, since it needs the verifier's own records.
+ */
+export declare function verifyChain(grants: unknown, rootKey: string): ChainResult;
+//# sourceMappingURL=grant.d.ts.map

package/dist/grant/grant.d.ts.map

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

package/dist/grant/grant.js

@@ -0,0 +1,158 @@
+import { hashData, isFreshExpiry, safeVerifyData, signData } from "../crypto/utils.js";
+/** Longest lifetime of one grant. Renewal extends access past it. */
+export const MAX_GRANT_LIFETIME_MS = 1000 * 60 * 60 * 24 * 30;
+/** Longest lifetime of an invocation authorization or a renewal request. */
+export const MAX_AUTHORIZATION_LIFETIME_MS = 1000 * 60 * 2;
+/** Longest delegation chain, root included. */
+export const MAX_GRANT_CHAIN_LENGTH = 4;
+/**
+ * How far ahead of the verifier's clock a signer's clock may run. Signers use the full lifetimes
+ * above, so verifiers accept expiries up to this much past them.
+ */
+export const CLOCK_SKEW_TOLERANCE_MS = 1000 * 30;
+/** The object a grant's signature covers: every field except `signature`. Key order is part of the signed bytes. */
+export function grantPayload(grant) {
+    const { id, issuer, issuerBaseUrl, audience, capabilities, issuedAt, expiresAt, parent } = grant;
+    return { id, issuer, issuerBaseUrl, audience, capabilities, issuedAt, expiresAt, parent };
+}
+/** Names a grant as a delegated grant's `parent`. Independent of the key order the grant arrived in. */
+export function grantHash(grant) {
+    return hashData({ ...grantPayload(grant), signature: grant.signature });
+}
+/** Key order is part of the signed bytes. */
+export function invocationAuthorizationPayload(payload) {
+    const { invocationHash, publicKey, nonce, expiresAt, grantsHash } = payload;
+    return { invocationHash, publicKey, nonce, expiresAt, grantsHash };
+}
+export function grantsHash(grants) {
+    return hashData(grants.map(grantHash));
+}
+/** Key order is part of the signed bytes. */
+export function grantRenewalPayload(request) {
+    const { grantId, publicKey, nonce, expiresAt } = request;
+    return { grantId, publicKey, nonce, expiresAt };
+}
+/** Key order is part of the signed bytes. Omitted `details` are signed as null. */
+export function grantRequestPayload(request) {
+    const { publicKey, capabilities, details, nonce, expiresAt } = request;
+    return { publicKey, capabilities, details: details ?? null, nonce, expiresAt };
+}
+export function signGrant(grant, privateKey) {
+    return { ...grantPayload(grant), signature: signData(grantPayload(grant), privateKey) };
+}
+const isString = (value) => typeof value === "string";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function isCapability(value) {
+    return isObject(value)
+        && isString(value.resourcePath) && value.resourcePath.length > 0
+        && (value.resourceName === undefined || isString(value.resourceName))
+        && (value.functionName === undefined || isString(value.functionName))
+        && (value.constraints === undefined || isObject(value.constraints));
+}
+export function isGrant(value) {
+    return isObject(value)
+        && isString(value.id) && isString(value.issuer) && isString(value.issuerBaseUrl) && isString(value.audience)
+        && Array.isArray(value.capabilities) && value.capabilities.length > 0 && value.capabilities.every(isCapability)
+        && isString(value.issuedAt) && isString(value.expiresAt)
+        && (value.parent === null || isString(value.parent))
+        && isString(value.signature);
+}
+export function isAuthorization(value) {
+    return isObject(value)
+        && isString(value.publicKey) && Array.isArray(value.grants) && isString(value.nonce) && isString(value.expiresAt) && isString(value.signature);
+}
+/** A `prefix.*` pattern's prefix, `''` for `*`, or undefined for an exact path. */
+function wildcardPrefix(pattern) {
+    if (pattern === "*") {
+        return "";
+    }
+    return pattern.endsWith(".*") ? pattern.slice(0, -2) : undefined;
+}
+/** Wildcards match on segment boundaries: `com.example.*` matches `com.example.sub` but not `com.examplefoo`. */
+function underPrefix(path, prefix) {
+    return prefix === "" || path === prefix || path.startsWith(`${prefix}.`);
+}
+function pathMatches(pattern, path) {
+    const prefix = wildcardPrefix(pattern);
+    return prefix === undefined ? pattern === path : underPrefix(path, prefix);
+}
+/** True when every path `child` matches is also matched by `parent`. */
+function pathCovers(parent, child) {
+    const parentPrefix = wildcardPrefix(parent);
+    if (parentPrefix === undefined) {
+        return parent === child;
+    }
+    const childPrefix = wildcardPrefix(child);
+    if (childPrefix === "") {
+        return parentPrefix === "";
+    }
+    return underPrefix(childPrefix ?? child, parentPrefix);
+}
+export function capabilityMatches(capability, resourcePath, resourceName, functionName, parameters) {
+    if (!pathMatches(capability.resourcePath, resourcePath)) {
+        return false;
+    }
+    if (capability.resourceName !== undefined && capability.resourceName !== resourceName) {
+        return false;
+    }
+    if (capability.functionName !== undefined && capability.functionName !== functionName) {
+        return false;
+    }
+    // A constrained parameter must appear exactly once, so a duplicate can't carry a different value past the check.
+    return Object.entries(capability.constraints ?? {}).every(([name, value]) => {
+        const matching = parameters.filter(p => p.name === name);
+        return matching.length === 1 && sameJson(matching[0].value, value);
+    });
+}
+/** True when `child` allows nothing `parent` doesn't. A delegated grant may only narrow its parent. */
+export function capabilityCovers(parent, child) {
+    if (!pathCovers(parent.resourcePath, child.resourcePath)) {
+        return false;
+    }
+    if (parent.resourceName !== undefined && child.resourceName !== parent.resourceName) {
+        return false;
+    }
+    if (parent.functionName !== undefined && child.functionName !== parent.functionName) {
+        return false;
+    }
+    const childConstraints = child.constraints ?? {};
+    return Object.entries(parent.constraints ?? {}).every(([name, value]) => name in childConstraints && sameJson(childConstraints[name], value));
+}
+/**
+ * Checks a chain's signatures, expiries and links, root first. Revocation is the caller's
+ * job, since it needs the verifier's own records.
+ */
+export function verifyChain(grants, rootKey) {
+    if (!Array.isArray(grants) || grants.length === 0 || grants.length > MAX_GRANT_CHAIN_LENGTH) {
+        return { ok: false, reason: "chain length" };
+    }
+    if (!grants.every(isGrant)) {
+        return { ok: false, reason: "malformed grant" };
+    }
+    for (const [index, grant] of grants.entries()) {
+        if (!isFreshExpiry(grant.expiresAt, MAX_GRANT_LIFETIME_MS + CLOCK_SKEW_TOLERANCE_MS)) {
+            return { ok: false, reason: `grant ${index} expired` };
+        }
+        if (!safeVerifyData(grantPayload(grant), grant.issuer, grant.signature)) {
+            return { ok: false, reason: `grant ${index} signature` };
+        }
+        if (index === 0) {
+            if (grant.parent !== null || grant.issuer !== rootKey) {
+                return { ok: false, reason: "root issuer" };
+            }
+            continue;
+        }
+        const parent = grants[index - 1];
+        if (grant.parent !== grantHash(parent) || grant.issuer !== parent.audience) {
+            return { ok: false, reason: `grant ${index} link` };
+        }
+        if (Date.parse(grant.expiresAt) > Date.parse(parent.expiresAt)) {
+            return { ok: false, reason: `grant ${index} outlives its parent` };
+        }
+        if (!grant.capabilities.every(child => parent.capabilities.some(capability => capabilityCovers(capability, child)))) {
+            return { ok: false, reason: `grant ${index} widens its parent` };
+        }
+    }
+    return { ok: true, leaf: grants[grants.length - 1] };
+}