@venturekit/runtime 0.0.0-dev.20260415182021 → 0.0.0-dev.20260427220257

package/dist/security/internal-hmac.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Internal-invocation HMAC signing.
+ *
+ * VentureKit functions can mark themselves as "internal" callers (e.g. to skip
+ * rate limiting or public-authentication middleware). Because all handlers sit
+ * behind API Gateway, a plain `x-venturekit-source: internal` header is
+ * forgeable — any external client could set it. To prevent that, every
+ * `invoke()` caller signs a short-lived HMAC over `${functionName}:${timestamp}`
+ * and the receiver verifies the signature against the shared secret.
+ *
+ * Secret resolution order:
+ *   1. `VENTURE_INTERNAL_HMAC_SECRET` env var (injected by CDK on every function
+ *      in the same project at deploy time).
+ *   2. `venturekit-local-dev-secret` fallback for local dev only — prints a
+ *      `once-per-process` warning.
+ *
+ * Replay window is 5 minutes (configurable via `VENTURE_INTERNAL_HMAC_TTL_MS`).
+ * Signatures outside that window are rejected.
+ */
+export declare const INTERNAL_HMAC_HEADERS: {
+    /** Marker that this is an internal invocation ("internal") */
+    readonly SOURCE: "x-venturekit-source";
+    /** Millisecond timestamp as a decimal string */
+    readonly TIMESTAMP: "x-venturekit-timestamp";
+    /** Hex-encoded HMAC-SHA256 signature */
+    readonly SIGNATURE: "x-venturekit-signature";
+    /** Unique invoke ID (opaque, purely for tracing) */
+    readonly INVOKE_ID: "x-venturekit-invoke-id";
+};
+/**
+ * Sign an internal invocation. Returns the headers that must be attached
+ * to the outbound Lambda payload.
+ *
+ * @param functionName - The resolved target Lambda function name.
+ * @param timestampMs  - Caller timestamp. Defaults to `Date.now()`; pass an
+ *                       explicit value for deterministic tests.
+ */
+export declare function signInternalCall(functionName: string, timestampMs?: number): {
+    timestamp: string;
+    signature: string;
+};
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: 'missing-headers' | 'bad-timestamp' | 'expired' | 'bad-signature';
+};
+/**
+ * Verify an internal-call signature against the current function's name.
+ *
+ * @param headers      - Lowercased header map from the Lambda event.
+ * @param functionName - Usually `process.env.AWS_LAMBDA_FUNCTION_NAME`. Callers
+ *                       may pass an explicit name for tests.
+ * @param nowMs        - Override for "now" in tests.
+ */
+export declare function verifyInternalCall(headers: Record<string, string | undefined> | undefined, functionName: string | undefined, nowMs?: number): VerifyResult;
+/** Reset the warned-about-fallback flag. Test-only helper. */
+export declare function __resetHmacWarningForTests(): void;
+//# sourceMappingURL=internal-hmac.d.ts.map

package/dist/security/internal-hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-hmac.d.ts","sourceRoot":"","sources":["../../src/security/internal-hmac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,eAAO,MAAM,qBAAqB;IAChC,8DAA8D;;IAE9D,gDAAgD;;IAEhD,wCAAwC;;IAExC,oDAAoD;;CAE5C,CAAC;AAqCX;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,WAAW,GAAE,MAAmB,GAC/B;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAI1C;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,SAAS,GAAG,eAAe,CAAA;CAAE,CAAC;AAEhG;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,EACvD,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,KAAK,GAAE,MAAmB,GACzB,YAAY,CA4Bd;AAED,8DAA8D;AAC9D,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/security/internal-hmac.js

@@ -0,0 +1,117 @@
+/**
+ * Internal-invocation HMAC signing.
+ *
+ * VentureKit functions can mark themselves as "internal" callers (e.g. to skip
+ * rate limiting or public-authentication middleware). Because all handlers sit
+ * behind API Gateway, a plain `x-venturekit-source: internal` header is
+ * forgeable — any external client could set it. To prevent that, every
+ * `invoke()` caller signs a short-lived HMAC over `${functionName}:${timestamp}`
+ * and the receiver verifies the signature against the shared secret.
+ *
+ * Secret resolution order:
+ *   1. `VENTURE_INTERNAL_HMAC_SECRET` env var (injected by CDK on every function
+ *      in the same project at deploy time).
+ *   2. `venturekit-local-dev-secret` fallback for local dev only — prints a
+ *      `once-per-process` warning.
+ *
+ * Replay window is 5 minutes (configurable via `VENTURE_INTERNAL_HMAC_TTL_MS`).
+ * Signatures outside that window are rejected.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const INTERNAL_HMAC_HEADERS = {
+    /** Marker that this is an internal invocation ("internal") */
+    SOURCE: 'x-venturekit-source',
+    /** Millisecond timestamp as a decimal string */
+    TIMESTAMP: 'x-venturekit-timestamp',
+    /** Hex-encoded HMAC-SHA256 signature */
+    SIGNATURE: 'x-venturekit-signature',
+    /** Unique invoke ID (opaque, purely for tracing) */
+    INVOKE_ID: 'x-venturekit-invoke-id',
+};
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const LOCAL_DEV_SECRET = 'venturekit-local-dev-secret';
+let warnedAboutFallback = false;
+/** Return the HMAC secret from env, falling back to a dev default. */
+function getSecret() {
+    const secret = process.env.VENTURE_INTERNAL_HMAC_SECRET;
+    if (secret && secret.length > 0)
+        return secret;
+    if (!warnedAboutFallback) {
+        warnedAboutFallback = true;
+        // eslint-disable-next-line no-console
+        console.warn('[venturekit] VENTURE_INTERNAL_HMAC_SECRET not set — using ' +
+            'insecure fallback for local development. In production, CDK injects ' +
+            'a per-project secret automatically; missing it means the function ' +
+            'was not deployed via `vk deploy`.');
+    }
+    return LOCAL_DEV_SECRET;
+}
+/** TTL window in ms beyond which signatures are rejected. */
+function getTtlMs() {
+    const raw = process.env.VENTURE_INTERNAL_HMAC_TTL_MS;
+    if (!raw)
+        return DEFAULT_TTL_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TTL_MS;
+}
+function hmacHex(secret, payload) {
+    return createHmac('sha256', secret).update(payload).digest('hex');
+}
+/**
+ * Sign an internal invocation. Returns the headers that must be attached
+ * to the outbound Lambda payload.
+ *
+ * @param functionName - The resolved target Lambda function name.
+ * @param timestampMs  - Caller timestamp. Defaults to `Date.now()`; pass an
+ *                       explicit value for deterministic tests.
+ */
+export function signInternalCall(functionName, timestampMs = Date.now()) {
+    const ts = String(timestampMs);
+    const signature = hmacHex(getSecret(), `${functionName}:${ts}`);
+    return { timestamp: ts, signature };
+}
+/**
+ * Verify an internal-call signature against the current function's name.
+ *
+ * @param headers      - Lowercased header map from the Lambda event.
+ * @param functionName - Usually `process.env.AWS_LAMBDA_FUNCTION_NAME`. Callers
+ *                       may pass an explicit name for tests.
+ * @param nowMs        - Override for "now" in tests.
+ */
+export function verifyInternalCall(headers, functionName, nowMs = Date.now()) {
+    if (!headers || !functionName)
+        return { valid: false, reason: 'missing-headers' };
+    const source = headers[INTERNAL_HMAC_HEADERS.SOURCE];
+    const ts = headers[INTERNAL_HMAC_HEADERS.TIMESTAMP];
+    const sig = headers[INTERNAL_HMAC_HEADERS.SIGNATURE];
+    if (source !== 'internal' || !ts || !sig) {
+        return { valid: false, reason: 'missing-headers' };
+    }
+    const tsNum = Number(ts);
+    if (!Number.isFinite(tsNum))
+        return { valid: false, reason: 'bad-timestamp' };
+    if (Math.abs(nowMs - tsNum) > getTtlMs())
+        return { valid: false, reason: 'expired' };
+    const expected = hmacHex(getSecret(), `${functionName}:${ts}`);
+    // Hex strings of the same byte length → safe for timingSafeEqual after buffering.
+    let expectedBuf;
+    let actualBuf;
+    try {
+        expectedBuf = Buffer.from(expected, 'hex');
+        actualBuf = Buffer.from(sig, 'hex');
+    }
+    catch {
+        return { valid: false, reason: 'bad-signature' };
+    }
+    if (expectedBuf.length === 0 || expectedBuf.length !== actualBuf.length) {
+        return { valid: false, reason: 'bad-signature' };
+    }
+    return timingSafeEqual(expectedBuf, actualBuf)
+        ? { valid: true }
+        : { valid: false, reason: 'bad-signature' };
+}
+/** Reset the warned-about-fallback flag. Test-only helper. */
+export function __resetHmacWarningForTests() {
+    warnedAboutFallback = false;
+}
+//# sourceMappingURL=internal-hmac.js.map

package/dist/security/internal-hmac.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit/runtime",
-  "version": "0.0.0-dev.20260415182021",
+  "version": "0.0.0-dev.20260427220257",
   "description": "VentureKit runtime utilities - handlers, context, middleware, logging",
   "type": "module",
   "main": "dist/index.js",
@@ -55,11 +55,11 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260415182021",
+    "@venturekit/core": "0.0.0-dev.20260427220257",
     "pino": "^9.0.0"
   },
   "peerDependencies": {
-    "@venturekit/data": "0.0.0-dev.20260415182021",
+    "@venturekit/data": "0.0.0-dev.20260427220257",
     "@aws-sdk/client-dynamodb": "^3.500.0",
     "@aws-sdk/lib-dynamodb": "^3.500.0",
     "@aws-sdk/client-lambda": "^3.500.0",
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@venturekit/data": "0.0.0-dev.20260415182021",
+    "@venturekit/data": "0.0.0-dev.20260427220257",
     "@types/aws-lambda": "^8.10.131",
     "@types/node": "^20.10.0",
     "@aws-sdk/client-lambda": "^3.500.0",