@shiprev/server-sdk-node 0.0.0-stage → 0.1.0-beta.1

package/dist/auth/token-verifier.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenVerifier = exports.JWKS_REFRESH_COOLDOWN_MS = void 0;
+exports.jwkToPem = jwkToPem;
+exports.expectationsFromMachineToken = expectationsFromMachineToken;
+exports.expiryOfToken = expiryOfToken;
+const crypto = __importStar(require("crypto"));
+const types_1 = require("../types");
+/** The audience and scope of the session tokens the portal issues to buyer end users. */
+const SESSION_AUDIENCE = 'public';
+function base64UrlDecode(str) {
+    let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+    while (base64.length % 4 !== 0) {
+        base64 += '=';
+    }
+    return Buffer.from(base64, 'base64');
+}
+function jwkToPem(jwk) {
+    const keyObj = crypto.createPublicKey({
+        key: {
+            kty: jwk.kty,
+            n: jwk.n,
+            e: jwk.e,
+        },
+        format: 'jwk',
+    });
+    return keyObj.export({ type: 'spki', format: 'pem' });
+}
+/**
+ * After a successful JWKS fetch, a token with an unknown `kid` does not trigger another fetch for
+ * this long; it is refused instead. Without it, an anonymous caller could turn every forged token
+ * carrying a random `kid` into one request to the instance. A key rotated in during this window is
+ * accepted at most this long after the previous fetch.
+ */
+exports.JWKS_REFRESH_COOLDOWN_MS = 30_000;
+class TokenVerifier {
+    transport;
+    publicKeyCache = new Map();
+    /** `Date.now()` of the last successful JWKS fetch; failed fetches do not set it. */
+    lastRefreshAt = null;
+    inFlightRefresh = null;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Refreshes the local in-memory public key cache from the JWKS endpoint. Always fetches (no
+     * cooldown); concurrent calls share one request. A success starts the unknown-`kid` cooldown.
+     */
+    async refreshKeys() {
+        if (!this.inFlightRefresh) {
+            this.inFlightRefresh = this.fetchKeys().finally(() => {
+                this.inFlightRefresh = null;
+            });
+        }
+        return this.inFlightRefresh;
+    }
+    async fetchKeys() {
+        const jwks = await this.transport.fetchJwks();
+        const pems = jwks.keys.map((key) => [key.kid, jwkToPem(key)]);
+        for (const [kid, pem] of pems) {
+            this.publicKeyCache.set(kid, pem);
+        }
+        this.lastRefreshAt = Date.now();
+    }
+    inRefreshCooldown() {
+        return this.lastRefreshAt !== null && Date.now() - this.lastRefreshAt < exports.JWKS_REFRESH_COOLDOWN_MS;
+    }
+    /**
+     * Directly caches a key in memory (e.g. for testing or preloading)
+     */
+    setPublicKey(kid, pem) {
+        this.publicKeyCache.set(kid, pem);
+    }
+    /**
+     * Verifies an RS256 JWT token locally, extracting the subject and isolation keys.
+     * If the kid is unknown in cache, it triggers a single JWKS refresh, unless the last successful
+     * refresh is less than `JWKS_REFRESH_COOLDOWN_MS` old, in which case the token is refused at once.
+     *
+     * With `expectations` (or `null`, meaning they are not known yet), the token must also be a buyer
+     * session token of that issuer and application; the checks run after the signature, in the order
+     * exp · purpose · aud/scope · iss · pid, and refusals are `TokenRejectedError`. Without the
+     * argument only the signature and, when present, the expiry are checked.
+     */
+    async verifyToken(token, expectations) {
+        if (!token || typeof token !== 'string') {
+            throw new Error('Token must be a non-empty string');
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            throw new Error('Invalid JWT format');
+        }
+        const [headerB64, payloadB64, signatureB64] = parts;
+        // Decode header to retrieve kid and alg
+        let header;
+        try {
+            header = JSON.parse(base64UrlDecode(headerB64).toString('utf-8'));
+        }
+        catch {
+            throw new Error('Invalid JWT header format');
+        }
+        if (header.alg !== 'RS256') {
+            throw new Error(`Unsupported JWT algorithm: ${header.alg ?? 'unknown'}, expected RS256`);
+        }
+        const kid = header.kid;
+        if (!kid) {
+            throw new Error('JWT header is missing kid');
+        }
+        // Lookup public key from local cache
+        let publicKeyPem = this.publicKeyCache.get(kid);
+        // Cache miss / key rotation: refresh keys once, outside the cooldown only
+        if (!publicKeyPem) {
+            if (this.inRefreshCooldown()) {
+                throw new Error(`Unknown key ID: kid=${kid}`);
+            }
+            await this.refreshKeys();
+            publicKeyPem = this.publicKeyCache.get(kid);
+            if (!publicKeyPem) {
+                throw new Error(`Unknown key ID: kid=${kid}`);
+            }
+        }
+        // Verify RS256 signature
+        const verifier = crypto.createVerify('RSA-SHA256');
+        verifier.update(`${headerB64}.${payloadB64}`);
+        verifier.end();
+        const signature = base64UrlDecode(signatureB64);
+        const isValid = verifier.verify(publicKeyPem, signature);
+        if (!isValid) {
+            throw new Error('Invalid JWT signature');
+        }
+        // Decode and validate payload claims
+        let payload;
+        try {
+            payload = JSON.parse(base64UrlDecode(payloadB64).toString('utf-8'));
+        }
+        catch {
+            throw new Error('Invalid JWT payload format');
+        }
+        // Expiration check
+        const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
+        if (exp !== undefined && exp * 1000 <= Date.now()) {
+            throw new Error('JWT token has expired');
+        }
+        if (expectations !== undefined) {
+            checkExpectations(payload, expectations);
+        }
+        const accountId = String(payload.sub ?? '');
+        const organizationId = String(payload.oid ?? '');
+        const projectId = String(payload.pid ?? '');
+        const tenantId = String(payload.tid ?? '');
+        const scope = String(payload.scope ?? '');
+        const keyVersion = typeof payload.ver === 'number' ? payload.ver : 1;
+        return {
+            account_id: accountId,
+            organization_id: organizationId,
+            project_id: projectId,
+            tenant_id: tenantId,
+            key_version: keyVersion,
+            scope,
+            exp: exp ?? 0,
+            iat: typeof payload.iat === 'number' ? payload.iat : undefined,
+            iss: typeof payload.iss === 'string' ? payload.iss : undefined,
+            sub: accountId,
+            aud: typeof payload.aud === 'string' ? payload.aud : undefined,
+        };
+    }
+}
+exports.TokenVerifier = TokenVerifier;
+/** Session-token checks of slice §5.3, in their fixed order. */
+function checkExpectations(payload, expectations) {
+    if (typeof payload.exp !== 'number') {
+        throw new types_1.TokenRejectedError('missing_expiry', 'Token rejected: it carries no expiry');
+    }
+    if (payload.purpose !== undefined) {
+        throw new types_1.TokenRejectedError('not_a_session_token', 'Token rejected: it is a one-time token, not a session token');
+    }
+    if (!expectations) {
+        throw new types_1.TokenRejectedError('not_ready', 'Token rejected: the client has no service token yet, so the expected issuer and application are unknown');
+    }
+    if (payload.aud !== SESSION_AUDIENCE || payload.scope !== SESSION_AUDIENCE) {
+        throw new types_1.TokenRejectedError('audience_mismatch', 'Token rejected: it is not a buyer session token');
+    }
+    if (payload.iss !== expectations.issuer) {
+        throw new types_1.TokenRejectedError('issuer_mismatch', 'Token rejected: it was issued by another instance');
+    }
+    if (payload.pid !== expectations.projectId) {
+        throw new types_1.TokenRejectedError('project_mismatch', 'Token rejected: it belongs to another application');
+    }
+}
+/**
+ * Reads the expectations from a machine token's payload without verifying it (the client obtained
+ * it from the instance itself). Returns `null` when the value is not a decodable JWT or lacks `iss`
+ * or `pid`.
+ */
+function expectationsFromMachineToken(token) {
+    const parts = typeof token === 'string' ? token.split('.') : [];
+    if (parts.length !== 3) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(base64UrlDecode(parts[1]).toString('utf-8'));
+        if (typeof payload.iss === 'string' && payload.iss && typeof payload.pid === 'string' && payload.pid) {
+            return { issuer: payload.iss, projectId: payload.pid };
+        }
+    }
+    catch {
+        // Not a JWT: no expectations.
+    }
+    return null;
+}
+/** The `exp` of a JWT in milliseconds, or `undefined` when it cannot be read. */
+function expiryOfToken(token) {
+    const parts = typeof token === 'string' ? token.split('.') : [];
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    try {
+        const payload = JSON.parse(base64UrlDecode(parts[1]).toString('utf-8'));
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=token-verifier.js.map

package/dist/client/connection-supervisor.d.ts

@@ -0,0 +1,148 @@
+import { EntitlementMirror } from '../mirror/entitlement-mirror';
+import { HttpTransport } from '../transport/http.transport';
+import { OrganizationSnapshot, Snapshot } from '../types';
+/**
+ * Keeps a started client connected to its instance, from `start()` to `stop()`:
+ *
+ * - holds the machine token and renews it at 80 % of its lifetime; a 401 on any authenticated
+ *   request triggers one shared renewal and a single retry;
+ * - holds the push stream `GET /sdk/v1/events`, which is the only online signal: the client is
+ *   online while the stream delivered `ready`, has not been silent for three heartbeat intervals,
+ *   and the mirror was pulled after the stream opened;
+ * - on a planned renewal opens a second stream with the new token and closes the old one once the
+ *   new one is ready, without pulling; on an unplanned break reconnects once at once, then backs
+ *   off (1, 2, 4, 8, 16, 30 s, ±20 %);
+ * - turns `snapshot.changed` into per-organization refills (at most one in flight per organization)
+ *   and `snapshot.resync` into a full pull;
+ * - while online, renews an organization entry that carries `valid_until` once half of its validity has passed
+ *   without a newer entry, with one pull of that organization. It never pulls on a fixed period.
+ *
+ * Every timer is unref'd, so the supervisor never keeps the host process alive.
+ */
+/** What the supervisor needs from the client it serves. */
+export interface SupervisorHost {
+    transport: HttpTransport;
+    mirror: EntitlementMirror;
+    apiKey: string;
+    connectTimeoutMs: number;
+    /** Fetches the signing keys. */
+    loadKeys(): Promise<void>;
+    /** A new machine token is in use. */
+    onToken(token: string): void;
+    /** The online signal changed. */
+    setOnline(online: boolean): void;
+    /** Delivers buffered and backlogged usage. */
+    flush(): Promise<void>;
+}
+/**
+ * What one per-organization pull did to the mirror: `applied` (the answer's entry is now the mirror's entry),
+ * `removed` (the answer no longer holds the organization and the mirror dropped it), or `ignored` (the answer
+ * was not used: a newer entry was already held or arrived meanwhile, an unsupported schema, or the client was
+ * stopped or paused meanwhile). Only an applied or removed pull is an answer about the organization.
+ */
+export interface OrganizationPull {
+    envelope: Snapshot;
+    outcome: 'applied' | 'removed' | 'ignored';
+    /** The mirror's entry after an applied pull. */
+    entry?: OrganizationSnapshot;
+}
+export declare class ConnectionSupervisor {
+    private readonly host;
+    private token;
+    private tokenExpiresAt;
+    private projectId;
+    private credentialRefused;
+    private exchangeInFlight;
+    private keysLoaded;
+    private stream;
+    private readonly streams;
+    private live;
+    private running;
+    private paused;
+    /** Bumped by stop, pause and start; work begun under an older generation drops its result. */
+    private generation;
+    private connecting;
+    private rotating;
+    private backoffStep;
+    private renewalBackoffStep;
+    /** When the next renewal is due (local clock), kept across a pause. */
+    private renewDueAt;
+    private renewTimer;
+    private reconnectTimer;
+    private watchdogTimer;
+    private renewalTimer;
+    private readonly refillTargets;
+    private readonly refillsInFlight;
+    /** Per-organization pulls in flight, shared by refills, renewals and `refresh()`. */
+    private readonly organizationPulls;
+    /** Organizations whose last renewal pull failed, with the time a renewal may be tried again. */
+    private readonly renewalRetryAt;
+    constructor(host: SupervisorHost);
+    /** The machine token in use, or `null`. */
+    currentToken(): string | null;
+    /**
+     * Keys, token, stream (waiting for `ready`), then a full pull. Never throws: whatever fails is
+     * retried in the background.
+     */
+    start(): Promise<void>;
+    /** Closes the stream and stops every timer. */
+    stop(): void;
+    /** `setOnline(false)`: closes the stream and suspends supervision until `resume()`. */
+    pause(): void;
+    /** `setOnline(true)`: resumes supervision; the next attempt corrects the state. */
+    resume(): void;
+    /** A token set by hand (`setM2MToken`): used as is, never renewed on a timer. */
+    injectToken(token: string): void;
+    /**
+     * Runs an authenticated request. A 401 triggers one renewal, shared by every request that failed
+     * with the same token, and one retry with the new token; a second failure is the request's own.
+     */
+    authorized<T>(call: (token: string) => Promise<T>): Promise<T>;
+    /**
+     * One attempt to get online. `initial` (start) pulls even when the stream cannot be opened, so the
+     * mirror is loaded; later attempts pull only once a stream is ready, except while the mirror is
+     * still empty.
+     */
+    private attempt;
+    private reconnect;
+    private scheduleReconnect;
+    private goLive;
+    private goOffline;
+    /** An unplanned break of the active stream: one immediate reconnect, still LIVE meanwhile. */
+    private onBreak;
+    private validToken;
+    private exchange;
+    private clearExchange;
+    private renewAfterUnauthorized;
+    private scheduleRenewal;
+    private renew;
+    /** A new token: rotate a live stream onto it, or reconnect if the client is not live. */
+    private afterRenewal;
+    /** Planned rotation: the new stream must be ready before the old one is closed; no pull. */
+    private rotate;
+    /** Opens a stream and resolves once its `ready` frame arrived (bounded by the connect timeout). */
+    private openStream;
+    private adopt;
+    private retire;
+    private armWatchdog;
+    private onFrame;
+    private onChanged;
+    /** Refills one organization until the mirror reaches the highest announced revision. */
+    private refill;
+    /**
+     * One pull of one organization, shared by every concurrent caller, merged into the mirror (or removing the
+     * organization when the answer no longer holds it). A pull that finishes after `stop()` or `pause()` leaves
+     * the mirror as it is.
+     */
+    pullOrganization(organizationId: string): Promise<OrganizationPull>;
+    /** Re-arms the renewal timer for the earliest entry due; nothing while offline. Called on every mirror change. */
+    scheduleRenewals(): void;
+    /** Halfway between receiving an entry and its `valid_until`; undefined for an entry without a usable one. */
+    private renewalDue;
+    private renewDueEntries;
+    /** Full pull: replaces the whole mirror. */
+    private pull;
+    /** Drops the stream, every timer and any attempt in flight. */
+    private halt;
+    private clearTimer;
+}