@koralabs/kora-labs-common 6.6.4 → 6.7.1

package/aws/index.d.ts

@@ -1,2 +1,3 @@
 export { decryptKmsCiphertext, hydrateKmsEnvironment, loadAfterHydratingKmsEnvironment } from './kmsEnvironment';
 export type { KmsClientLike } from './kmsEnvironment';
+export { signRs256, verifyRs256, isLocalJwtSigner } from './jwtSigner';

package/aws/index.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadAfterHydratingKmsEnvironment = exports.hydrateKmsEnvironment = exports.decryptKmsCiphertext = void 0;
+exports.isLocalJwtSigner = exports.verifyRs256 = exports.signRs256 = exports.loadAfterHydratingKmsEnvironment = exports.hydrateKmsEnvironment = exports.decryptKmsCiphertext = void 0;
 var kmsEnvironment_1 = require("./kmsEnvironment");
 Object.defineProperty(exports, "decryptKmsCiphertext", { enumerable: true, get: function () { return kmsEnvironment_1.decryptKmsCiphertext; } });
 Object.defineProperty(exports, "hydrateKmsEnvironment", { enumerable: true, get: function () { return kmsEnvironment_1.hydrateKmsEnvironment; } });
 Object.defineProperty(exports, "loadAfterHydratingKmsEnvironment", { enumerable: true, get: function () { return kmsEnvironment_1.loadAfterHydratingKmsEnvironment; } });
+var jwtSigner_1 = require("./jwtSigner");
+Object.defineProperty(exports, "signRs256", { enumerable: true, get: function () { return jwtSigner_1.signRs256; } });
+Object.defineProperty(exports, "verifyRs256", { enumerable: true, get: function () { return jwtSigner_1.verifyRs256; } });
+Object.defineProperty(exports, "isLocalJwtSigner", { enumerable: true, get: function () { return jwtSigner_1.isLocalJwtSigner; } });

package/aws/jwtSigner.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/** True when a local RSA key is configured (i.e. signing/verifying needs no AWS). */
+export declare const isLocalJwtSigner: () => boolean;
+/** Sign `message` with RS256 — local private key if present, else AWS KMS. */
+export declare const signRs256: (message: Buffer) => Promise<Buffer>;
+/** Verify an RS256 `signature` over `message` — local public key if present, else AWS KMS. */
+export declare const verifyRs256: (message: Buffer, signature: Buffer) => Promise<boolean>;

package/aws/jwtSigner.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyRs256 = exports.signRs256 = exports.isLocalJwtSigner = void 0;
+const client_kms_1 = require("@aws-sdk/client-kms");
+const crypto_1 = require("crypto");
+// RS256 (RSASSA_PKCS1_V1_5_SHA_256) sign/verify primitive shared by the JWT-issuing/
+// verifying services (auth.handle.me grant cookie, handle.me/minting session tokens).
+//
+// It PREFERS a LOCAL RSA key — for the self-hosted deployment with no AWS — and FALLS
+// BACK to AWS KMS (JWT_KEY_ID) when no local key is configured, so existing KMS-backed
+// deployments keep working byte-for-byte and adoption can be gradual.
+//
+//   JWT_PRIVATE_KEY  RSA private key (PEM, or base64-encoded PEM) — used to SIGN. The
+//                    public half is derived from it for verification, so a single shared
+//                    secret (the private key) is enough on every node.
+//   JWT_PUBLIC_KEY   (optional) RSA public key (PEM/base64) for verify-only nodes that
+//                    should not hold the private key.
+//   JWT_KEY_ID       AWS KMS key id/alias (legacy fallback when no local key is set).
+//
+// These callers sign/verify over different bytes (auth signs the payload only; the
+// session-token path signs `header.payload`), so this stays a low-level bytes-in/bytes-out
+// primitive — each service keeps building its own token exactly as before.
+const SIGNING_ALGORITHM = 'RSASSA_PKCS1_V1_5_SHA_256';
+let _kms;
+const kms = () => (_kms !== null && _kms !== void 0 ? _kms : (_kms = new client_kms_1.KMSClient({})));
+// Accept a raw PEM or a base64-encoded PEM (single-line, env-friendly).
+const pemFromEnv = (value) => {
+    if (!value)
+        return undefined;
+    if (value.includes('-----BEGIN'))
+        return value;
+    try {
+        const decoded = Buffer.from(value, 'base64').toString('utf-8');
+        return decoded.includes('-----BEGIN') ? decoded : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
+const localPrivateKey = () => pemFromEnv(process.env.JWT_PRIVATE_KEY);
+const localPublicKey = () => {
+    const pub = pemFromEnv(process.env.JWT_PUBLIC_KEY);
+    if (pub)
+        return pub;
+    const priv = localPrivateKey();
+    if (!priv)
+        return undefined;
+    return (0, crypto_1.createPublicKey)(priv).export({ type: 'spki', format: 'pem' }).toString();
+};
+/** True when a local RSA key is configured (i.e. signing/verifying needs no AWS). */
+const isLocalJwtSigner = () => !!localPrivateKey() || !!pemFromEnv(process.env.JWT_PUBLIC_KEY);
+exports.isLocalJwtSigner = isLocalJwtSigner;
+/** Sign `message` with RS256 — local private key if present, else AWS KMS. */
+const signRs256 = async (message) => {
+    const priv = localPrivateKey();
+    if (priv) {
+        const signer = (0, crypto_1.createSign)('RSA-SHA256');
+        signer.update(message);
+        signer.end();
+        return signer.sign(priv);
+    }
+    const keyId = process.env.JWT_KEY_ID;
+    if (!keyId)
+        throw new Error('JWT_KEY_ID not configured');
+    const response = await kms().send(new client_kms_1.SignCommand({
+        KeyId: keyId,
+        Message: new Uint8Array(message),
+        MessageType: 'RAW',
+        SigningAlgorithm: SIGNING_ALGORITHM
+    }));
+    if (!response.Signature)
+        throw new Error('KMS sign returned no signature');
+    return Buffer.from(response.Signature);
+};
+exports.signRs256 = signRs256;
+/** Verify an RS256 `signature` over `message` — local public key if present, else AWS KMS. */
+const verifyRs256 = async (message, signature) => {
+    const pub = localPublicKey();
+    if (pub) {
+        const verifier = (0, crypto_1.createVerify)('RSA-SHA256');
+        verifier.update(message);
+        verifier.end();
+        return verifier.verify(pub, signature);
+    }
+    const keyId = process.env.JWT_KEY_ID;
+    if (!keyId)
+        throw new Error('JWT_KEY_ID not configured');
+    const response = await kms().send(new client_kms_1.VerifyCommand({
+        KeyId: keyId,
+        Message: new Uint8Array(message),
+        MessageType: 'RAW',
+        Signature: new Uint8Array(signature),
+        SigningAlgorithm: SIGNING_ALGORITHM
+    }));
+    return !!response.SignatureValid;
+};
+exports.verifyRs256 = verifyRs256;

package/fn/index.d.ts

@@ -0,0 +1,45 @@
+/// <reference types="node" />
+/// <reference types="node" />
+interface AlbEvent {
+    requestContext: {
+        elb: {
+            targetGroupArn: string;
+        };
+    };
+    httpMethod: string;
+    path: string;
+    queryStringParameters: Record<string, string> | null;
+    multiValueQueryStringParameters?: Record<string, string[]> | null;
+    headers: Record<string, string>;
+    body: string | null;
+    isBase64Encoded: boolean;
+}
+interface AlbResult {
+    statusCode?: number;
+    statusDescription?: string;
+    headers?: Record<string, string | number | boolean>;
+    multiValueHeaders?: Record<string, Array<string | number | boolean>>;
+    body?: string;
+    isBase64Encoded?: boolean;
+}
+export type AlbHandler = (event: AlbEvent, context: Record<string, unknown>) => Promise<AlbResult> | AlbResult;
+export interface FnHttpGateway {
+    requestURL: string;
+    method: string;
+    headers: Record<string, string | string[]>;
+    statusCode: number;
+    setResponseHeader(key: string, ...values: string[]): void;
+    addResponseHeader(key: string, ...values: string[]): void;
+}
+export interface FnContext {
+    httpGateway?: FnHttpGateway;
+}
+/**
+ * Drive an app's ALB (serverless-express) handler from an Fn HTTP invocation.
+ * @param albHandler the app's existing @vendia/serverless-express handler
+ * @param ctx        the Fn FDK context (must be HTTP-triggered → ctx.httpGateway present)
+ * @param input      the request body (Buffer, with fdk inputMode 'buffer')
+ * @returns the response body (Buffer or string); status + headers are set on ctx.httpGateway
+ */
+export declare const invokeExpressViaAlb: (albHandler: AlbHandler, ctx: FnContext, input?: Buffer | Uint8Array | string) => Promise<Buffer | string>;
+export {};

package/fn/index.js

@@ -0,0 +1,77 @@
+"use strict";
+// Fn <-> Express bridge for the self-hosted runtime (MIGRATION-PLAN §4).
+//
+// Each app already exposes an @vendia/serverless-express ALB handler (e.g.
+// lambdas/api.app.ts `handler(event, ctx)`), which is how it ran on Lambda/ALB. Rather
+// than invent a new req/res bridge, `invokeExpressViaAlb` adapts an Fn HTTP-trigger
+// invocation INTO an ALB event, calls that existing handler, and maps the ALB response
+// back to Fn. So the Fn function reuses the exact Express request handling the app already
+// has, and apps need only a tiny func.js entrypoint:
+//
+//   const fdk = require('@fnproject/fdk');
+//   const { handler } = require('./dist/lambdas/api.app');           // the app's ALB handler
+//   const { invokeExpressViaAlb } = require('@koralabs/kora-labs-common');
+//   fdk.handle((input, ctx) => invokeExpressViaAlb(handler, ctx, input), { inputMode: 'buffer' });
+//
+// Typed loosely (no @types/aws-lambda / @fnproject/fdk dependency here) — the shapes below
+// match the ALB event/result and the Fn HTTPGatewayContext.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invokeExpressViaAlb = void 0;
+const flattenHeaders = (h) => {
+    const out = {};
+    for (const [k, v] of Object.entries(h || {})) {
+        out[k.toLowerCase()] = Array.isArray(v) ? v.join(', ') : String(v);
+    }
+    return out;
+};
+/**
+ * Drive an app's ALB (serverless-express) handler from an Fn HTTP invocation.
+ * @param albHandler the app's existing @vendia/serverless-express handler
+ * @param ctx        the Fn FDK context (must be HTTP-triggered → ctx.httpGateway present)
+ * @param input      the request body (Buffer, with fdk inputMode 'buffer')
+ * @returns the response body (Buffer or string); status + headers are set on ctx.httpGateway
+ */
+const invokeExpressViaAlb = async (albHandler, ctx, input) => {
+    var _a;
+    const h = ctx.httpGateway;
+    if (!h)
+        throw new Error('invokeExpressViaAlb: ctx.httpGateway missing (the function must be HTTP-triggered)');
+    // requestURL may be a bare path (`/handles?x=1`) or absolute; URL() needs a base.
+    const url = new URL(h.requestURL, 'http://kora.local');
+    const qs = {};
+    const mqs = {};
+    for (const key of new Set(url.searchParams.keys())) {
+        const all = url.searchParams.getAll(key);
+        qs[key] = all[all.length - 1];
+        mqs[key] = all;
+    }
+    const bodyBuf = input == null
+        ? Buffer.alloc(0)
+        : Buffer.isBuffer(input) ? input : Buffer.from(input);
+    const event = {
+        requestContext: { elb: { targetGroupArn: 'arn:kora:fn' } },
+        httpMethod: h.method,
+        path: url.pathname,
+        queryStringParameters: Object.keys(qs).length ? qs : null,
+        multiValueQueryStringParameters: Object.keys(mqs).length ? mqs : null,
+        headers: flattenHeaders(h.headers),
+        body: bodyBuf.length ? bodyBuf.toString('base64') : null,
+        isBase64Encoded: true
+    };
+    const res = (await albHandler(event, {})) || {};
+    h.statusCode = (_a = res.statusCode) !== null && _a !== void 0 ? _a : 200;
+    if (res.headers) {
+        for (const [k, v] of Object.entries(res.headers))
+            h.setResponseHeader(k, String(v));
+    }
+    if (res.multiValueHeaders) {
+        for (const [k, arr] of Object.entries(res.multiValueHeaders)) {
+            for (const v of arr)
+                h.addResponseHeader(k, String(v));
+        }
+    }
+    if (res.body == null)
+        return '';
+    return res.isBase64Encoded ? Buffer.from(res.body, 'base64') : res.body;
+};
+exports.invokeExpressViaAlb = invokeExpressViaAlb;

package/index.d.ts

@@ -2,6 +2,7 @@ export * from './constants';
 export * from './aws';
 export { ComputeEnvironment, Environment } from './environment';
 export * from './errors';
+export * from './fn';
 export * from './handles';
 export * from './http';
 export { LogCategory, Logger } from './logger';

package/index.js

@@ -21,6 +21,7 @@ var environment_1 = require("./environment");
 Object.defineProperty(exports, "ComputeEnvironment", { enumerable: true, get: function () { return environment_1.ComputeEnvironment; } });
 Object.defineProperty(exports, "Environment", { enumerable: true, get: function () { return environment_1.Environment; } });
 __exportStar(require("./errors"), exports);
+__exportStar(require("./fn"), exports);
 __exportStar(require("./handles"), exports);
 __exportStar(require("./http"), exports);
 var logger_1 = require("./logger");

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koralabs/kora-labs-common",
-    "version": "6.6.4",
+    "version": "6.7.1",
     "description": "Kora Labs Common Utilities",
     "main": "index.js",
     "types": "index.d.ts",