@aws-blocks/core 0.1.0

package/src/server/withAuth.ts

@@ -0,0 +1,323 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { ApiError } from '../errors.js';
+
+declare global {
+  var __BLOCKS_REQUEST_COOKIES_STORE__: AsyncLocalStorage<string> | undefined;
+}
+
+function getSsrCookies(): string | undefined {
+  const store = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+  if (!store || typeof store.getStore !== 'function') return undefined;
+  return store.getStore();
+}
+
+/**
+ * Get or lazily create the request cookie AsyncLocalStorage.
+ *
+ * In the API Lambda, `lambda-handler.ts` creates the store and registers it
+ * on `globalThis.__BLOCKS_REQUEST_COOKIES_STORE__`. In the SSR Lambda (a separate
+ * process), the store may not exist yet — this function creates it on demand.
+ *
+ * This module is server-only (never bundled for the browser), so direct
+ * `node:async_hooks` import is safe — no `webpackIgnore` needed.
+ */
+function getRequestCookieStore(): AsyncLocalStorage<string> {
+  const existing = globalThis.__BLOCKS_REQUEST_COOKIES_STORE__;
+  if (existing) return existing;
+
+  const store = new AsyncLocalStorage<string>();
+  globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+  return store;
+}
+
+// ---------------------------------------------------------------------------
+// Cookie Provider Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * A function that attempts to detect cookies from a specific framework's
+ * request context. Returns the cookie string if available, or `undefined`
+ * if the framework is not active or no cookies are present.
+ */
+export type CookieProvider = () => Promise<string | undefined>;
+
+const providers: Array<{ name: string; detect: CookieProvider }> = [];
+
+/**
+ * Register a framework-specific cookie provider for `withAuth()`.
+ *
+ * Providers are tried in registration order when `withAuth()` is called
+ * without explicit cookies. The first provider that returns a non-undefined
+ * value wins.
+ *
+ * Two providers are registered by default:
+ *
+ * - **Next.js** — reads cookies from `next/headers`. Works out of the box.
+ * - **Nuxt/Nitro** — reads cookies from the active Nitro request event
+ *   (via the `unctx` `'nitro-app'` async context). Requires
+ *   `nitro.experimental.asyncContext: true` in `nuxt.config.ts` so Nitro
+ *   wraps each request in an `AsyncLocalStorage` context. Without that
+ *   flag the provider returns `undefined` and a warning is emitted on
+ *   first miss to point at the missing config (see `withAuth` for the
+ *   no-cookies error path).
+ *
+ * Use this to add support for additional frameworks (SvelteKit, Astro, etc.)
+ * or custom cookie sources.
+ *
+ * @param name - Human-readable provider name (for debugging).
+ * @param detect - Async function that returns a cookie string or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * import { registerCookieProvider } from '@aws-blocks/blocks/server';
+ *
+ * // SvelteKit provider
+ * registerCookieProvider('sveltekit', async () => {
+ *   try {
+ *     const { getRequestEvent } = await import('$app/server');
+ *     const event = getRequestEvent();
+ *     return event?.request.headers.get('cookie') ?? undefined;
+ *   } catch {
+ *     return undefined;
+ *   }
+ * });
+ * ```
+ */
+export function registerCookieProvider(name: string, detect: CookieProvider): void {
+  const existingIdx = providers.findIndex(p => p.name === name);
+  if (existingIdx >= 0) {
+    providers[existingIdx] = { name, detect };
+  } else {
+    providers.push({ name, detect });
+  }
+}
+
+// Built-in Next.js provider — registered by default
+registerCookieProvider('nextjs', async () => {
+  try {
+    const mod = await import('next/headers');
+    const store = await mod.cookies();
+    const all = store.getAll();
+    if (all.length === 0) return undefined;
+    return all.map((c: { name: string; value: string }) => `${c.name}=${c.value}`).join('; ');
+  } catch {
+    return undefined;
+  }
+});
+
+// Built-in Nuxt/Nitro provider — requires `nitro.experimental.asyncContext: true`
+//
+// Reads the active request event from Nitro's async context, keyed
+// `'nitro-app'` in `unctx`. Nitro's *documented* entry point for this is
+// `useEvent()` from `nitropack/runtime` — but we deliberately do NOT use
+// it here, and reach into `unctx.getContext('nitro-app')` directly instead.
+//
+// WHY (do not "fix" this back to `nitropack/runtime`): `@aws-blocks/core`
+// is framework-agnostic. `withAuth` is re-exported through
+// `@aws-blocks/blocks/server` and gets transitively imported by Next.js
+// apps (and any other framework). `nitropack/runtime`'s entrypoint pulls
+// in `#nitro-internal-virtual/*` subpath imports that ONLY resolve inside
+// a Nitro build — webpack/Next.js can't resolve them and the consumer's
+// `next build` fails with "Module not found: Can't resolve
+// '#nitro-internal-virtual/error-handler'". `unctx` is a standalone leaf
+// utility with no virtual imports, so it bundles cleanly from any
+// framework. The documented-vs-internal-key trade-off loses to the
+// bundler-safety requirement for a cross-framework package.
+//
+// Both approaches ride the same experimental async-context machinery and
+// both require `experimental.asyncContext: true`. `nitroApp.use()` throws
+// when no context instance is bound (the flag-off signature), which we
+// distinguish from "not a Nitro app at all" below.
+/** Minimal shape of the h3 `H3Event` we read from (Nitro v2 / Nuxt 4). */
+type NitroH3Event = { node?: { req?: { headers?: { cookie?: string } } } };
+
+let nuxtAsyncContextWarned = false;
+registerCookieProvider('nuxt', async () => {
+  let getContext: typeof import('unctx').getContext;
+  try {
+    ({ getContext } = await import('unctx'));
+  } catch {
+    return undefined; // unctx not installed → not a Nuxt/Nitro app
+  }
+
+  // `getContext('nitro-app')` itself never throws — it lazily creates the
+  // context registry. `.use()` is what throws when no instance is bound.
+  const nitroAsyncContext = getContext('nitro-app');
+  let bound: { event?: NitroH3Event; request?: Request } | undefined;
+  try {
+    // `.use()` returns the bound NitroApp or throws.
+    //
+    // TODO(nitro-v3 / nuxt-5): Nitro v3 swaps h3 for srvx, so the bound
+    // context shape changes from `{ event }` (h3 `H3Event`, read below via
+    // `event.node.req.headers.cookie`) to `{ request }` (a standard Web
+    // `Request`, read via `request.headers.get('cookie')`). We read both
+    // shapes below so the provider keeps working across the cutover; revisit
+    // and drop the h3 branch once Nuxt 5 / Nitro v3 is the floor.
+    bound = nitroAsyncContext.use() as typeof bound;
+  } catch {
+    // In a Nitro runtime but no context bound for this call — almost
+    // always `experimental.asyncContext: true` missing from the config.
+    // Surface a hint exactly once per process so the developer sees the
+    // root cause, not a downstream generic "no cookies" 401. Suppressible
+    // via env var for tests / intentional setups.
+    if (
+      !nuxtAsyncContextWarned &&
+      process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN !== '1'
+    ) {
+      nuxtAsyncContextWarned = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[@aws-blocks/core] withAuth: Nuxt/Nitro detected but the request context is not available. ' +
+          "Add `nitro: { experimental: { asyncContext: true } }` to nuxt.config.ts so withAuth() can read cookies from the active request. " +
+          'See https://nuxt.com/docs/guide/going-further/experimental-features#asynccontext',
+      );
+    }
+    return undefined;
+  }
+
+  // h3 (Nitro v2): cookie lives on the Node request headers.
+  // srvx (Nitro v3): cookie lives on the Web `Request` headers. See the
+  // TODO above — the `request` branch future-proofs this for Nuxt 5.
+  const cookie =
+    bound?.event?.node?.req?.headers?.cookie ??
+    bound?.request?.headers?.get('cookie') ??
+    undefined;
+  return typeof cookie === 'string' && cookie.length > 0 ? cookie : undefined;
+});
+
+/**
+ * Try each registered provider in order; return the first non-undefined result.
+ */
+async function detectFrameworkCookies(): Promise<string | undefined> {
+  for (const provider of providers) {
+    const result = await provider.detect();
+    if (result) return result;
+  }
+  return undefined;
+}
+
+/**
+ * Clear all registered cookie providers, including the built-in Next.js one.
+ *
+ * Primarily useful for testing. After calling this, you must re-register any
+ * providers you need (including Next.js if desired).
+ *
+ * @example
+ * ```typescript
+ * import { clearCookieProviders, registerCookieProvider } from '@aws-blocks/blocks/server';
+ *
+ * // In test setup
+ * clearCookieProviders();
+ * registerCookieProvider('test', async () => 'session=test');
+ * ```
+ */
+export function clearCookieProviders(): void {
+  providers.length = 0;
+}
+
+/** @internal Read-only view of registered providers (for testing). */
+export function _getProviders(): ReadonlyArray<{ name: string; detect: CookieProvider }> {
+  return providers;
+}
+
+/**
+ * Wraps an async function with authenticated cookie forwarding for SSR.
+ *
+ * In SSR server components, browser cookies aren't automatically forwarded
+ * to API calls. This wrapper reads cookies and makes them available to
+ * all Blocks API calls within the callback via `AsyncLocalStorage`.
+ *
+ * **Resolution order:**
+ * 1. Explicit `cookies` parameter (framework-agnostic)
+ * 2. Existing request context (Lambda handler already set it up)
+ * 3. Registered cookie providers — Next.js and Nuxt are built-in, plus any
+ *    you've added via `registerCookieProvider`
+ * 4. Throws if no cookies found
+ *
+ * **Built-in providers:**
+ *
+ * | Framework | Source | Notes |
+ * |-----------|--------|-------|
+ * | Next.js | `next/headers` | Works out of the box. |
+ * | Nuxt/Nitro | Nitro async context (via `unctx`) | Requires `nitro: { experimental: { asyncContext: true } }` in `nuxt.config.ts`. With the flag off the provider returns `undefined` and emits a one-time warning naming the missing config. |
+ *
+ * @param fn - Async function containing Blocks API calls that need auth.
+ * @param cookies - Optional explicit cookie string. If omitted, auto-detects
+ *   from the request context or registered providers. Pass this for frameworks
+ *   without a registered provider (or use `registerCookieProvider` to add one).
+ * @returns The return value of `fn`.
+ *
+ * @example
+ * ```typescript
+ * // Next.js — auto-detects cookies from next/headers (built-in provider)
+ * import { withAuth } from '@aws-blocks/blocks/server';
+ *
+ * const posts = await withAuth(() => api.listMyPosts());
+ *
+ * // Multiple calls in one scope
+ * const data = await withAuth(async () => {
+ *   const posts = await api.listMyPosts();
+ *   const profile = await api.getProfile();
+ *   return { posts, profile };
+ * });
+ *
+ * // Explicit cookies for any framework
+ * const posts = await withAuth(
+ *   () => api.listMyPosts(),
+ *   request.headers.get('cookie'),
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Nuxt — auto-detects cookies via the active Nitro request event
+ * // (built-in provider). Requires the experimental.asyncContext flag.
+ * //
+ * // nuxt.config.ts
+ * // export default defineNuxtConfig({
+ * //   nitro: { experimental: { asyncContext: true } },
+ * // });
+ * //
+ * // server/api/posts.get.ts
+ * import { withAuth } from '@aws-blocks/blocks/server';
+ *
+ * export default defineEventHandler(async () => {
+ *   return withAuth(() => api.listMyPosts());
+ * });
+ * ```
+ *
+ * @throws {Error} If no cookies are found and no provider detected them.
+ */
+export async function withAuth<T>(
+  fn: () => Promise<T>,
+  cookies?: string | null,
+): Promise<T> {
+  if (cookies != null && cookies.trim()) {
+    const store = getRequestCookieStore();
+    return store.run(cookies, fn);
+  }
+
+  const existing = getSsrCookies();
+  if (existing) {
+    return fn();
+  }
+
+  const detected = await detectFrameworkCookies();
+  if (detected) {
+    const store = getRequestCookieStore();
+    return store.run(detected, fn);
+  }
+
+  const providerNames = providers.map(p => p.name).join(', ');
+  throw new ApiError(
+    `withAuth: No authentication cookies found. ` +
+    `Tried providers: [${providerNames || 'none registered'}]. ` +
+    `Ensure the user is logged in and cookies are being forwarded, ` +
+    `or pass cookies explicitly as the second argument.`,
+    401,
+  );
+}

package/src/telemetry/client.ts

@@ -0,0 +1,226 @@
+import { request as httpsRequest } from 'node:https';
+import { request as httpRequest } from 'node:http';
+import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync, writeFileSync, constants } from 'node:fs';
+import path from 'node:path';
+import { debuglog } from 'node:util';
+import { CORE_VERSION } from '../version.js';
+import { Scope } from '../common/index.js';
+import { isTelemetryEnabled } from './consent.js';
+import { collectEnvironment } from './environment.js';
+import { getInstallationId, getProjectId, generateEventId } from './identifiers.js';
+import type { BlocksTelemetryEvent, BuildAndSendEventOptions } from './types.js';
+
+// Debug log: writes to stderr via NODE_DEBUG=blocks-telemetry (developer-facing, for troubleshooting)
+const debug = debuglog('blocks-telemetry');
+
+const DEFAULT_ENDPOINT = 'https://blocks-telemetry.us-east-1.api.aws/metrics';
+const TIMEOUT_MS = 500;
+const TELEMETRY_VERSION = '1.0.0';
+
+function getEndpoint(): string {
+  return process.env.BLOCKS_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT;
+}
+
+/**
+ * Parse `--telemetry-file=/path/to/file.json` from process.argv.
+ *
+ * Supports both `--telemetry-file=path` and `--telemetry-file path` forms.
+ *
+ * @returns The file path if the flag is present, undefined otherwise.
+ *
+ * @example
+ * // Capture telemetry to file (also sends HTTP when enabled):
+ * // npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ *
+ * // Capture WITHOUT sending (disable HTTP, file still writes):
+ * // AWS_BLOCKS_DISABLE_TELEMETRY=1 npx tsx aws-blocks/scripts/server.ts --telemetry-file=/tmp/events.json
+ */
+export function getTelemetryFilePath(): string | undefined {
+  const arg = process.argv.find(a => a.startsWith('--telemetry-file='));
+  if (arg) {
+    const p = arg.slice('--telemetry-file='.length);
+    return p.trim() === '' ? undefined : p;
+  }
+  const idx = process.argv.indexOf('--telemetry-file');
+  if (idx !== -1 && process.argv[idx + 1] && !process.argv[idx + 1].startsWith('-')) {
+    return process.argv[idx + 1];
+  }
+  return undefined;
+}
+
+// File sink: writes to --telemetry-file path (user-facing, for debugging/testing)
+function writeToTelemetryFile(event: BlocksTelemetryEvent): void {
+  const filePath = getTelemetryFilePath();
+  if (!filePath) return;  // getTelemetryFilePath already rejects empty/whitespace
+
+  try {
+    const dir = path.dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // O_CREAT | O_EXCL: atomic create — fails with EEXIST if file already exists
+    const fd = openSync(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+    const content = JSON.stringify([event], null, 2);
+    writeSync(fd, content);
+    closeSync(fd);
+  } catch (err: any) {
+    // EEXIST = file already existed → skip (protects user data)
+    // All other errors silently ignored — telemetry must never affect commands
+  }
+}
+
+/**
+ * Constructs a telemetry event without sending it.
+ * Useful for testing event structure without I/O side effects.
+ * @internal
+ */
+export function buildEvent(opts: BuildAndSendEventOptions): BlocksTelemetryEvent {
+  const { blocks, totalCount, customBlocksCount } = Scope.getRegisteredBlocks();
+
+  let templateName: string | undefined = opts.product?.template;
+  let templateVersion: string | undefined = opts.product?.templateVersion;
+  try {
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.blocksTemplate) templateName = templateName || pkg.blocksTemplate;
+      if (pkg.blocksTemplateVersion) templateVersion = templateVersion || pkg.blocksTemplateVersion;
+    }
+  } catch {
+    // template info is best-effort
+  }
+
+  const buildingBlocks = blocks;
+
+  return {
+    telemetryVersion: TELEMETRY_VERSION,
+    identifiers: {
+      installationId: getInstallationId(),
+      projectId: getProjectId(),
+      eventId: generateEventId(),
+      timestamp: new Date().toISOString(),
+    },
+    event: {
+      command: opts.command,
+      state: opts.state,
+      duration: opts.duration,
+      ...(opts.error && { error: opts.error }),
+    },
+    environment: collectEnvironment(),
+    product: {
+      blocksVersion: CORE_VERSION,
+      ...(opts.product?.cdkVersion && { cdkVersion: opts.product.cdkVersion }),
+      ...(opts.product?.framework && { framework: opts.product.framework }),
+      ...(templateName && {
+        template: {
+          name: templateName,
+          ...(templateVersion && { version: templateVersion }),
+        },
+      }),
+      ...(buildingBlocks.length > 0 && { buildingBlocks }),
+    },
+    ...(opts.counters || totalCount > 0 || customBlocksCount > 0
+      ? {
+          counters: {
+            blocksCount: opts.counters?.blocksCount ?? totalCount,
+            ...(opts.counters?.customBuildingBlocks !== undefined
+              ? { customBuildingBlocks: opts.counters.customBuildingBlocks }
+              : customBlocksCount > 0 ? { customBuildingBlocks: customBlocksCount } : undefined),
+          },
+        }
+      : undefined),
+  };
+}
+
+/**
+ * Build a complete telemetry event and send it to the collection endpoint.
+ *
+ * This is the single entry point for all telemetry emission. It handles:
+ * 1. Early exit — if telemetry is disabled AND no `--telemetry-file` is set,
+ *    returns immediately with no side effects (no IDs persisted, no notice)
+ * 2. Full payload construction (identifiers, environment, product info)
+ * 3. File sink — writes to the file specified by `--telemetry-file` (if set),
+ *    regardless of opt-out status (inspired by CDK CLI's --telemetry-file)
+ * 4. Privacy filtering — custom BB names are NEVER sent, only counted
+ * 5. HTTP sink — fire-and-forget POST (only when telemetry is enabled)
+ *
+ * The file sink fires unconditionally when `--telemetry-file` is set.
+ * The HTTP sink only fires when telemetry is enabled. Callers never need to
+ * import consent, identifier, or environment utilities directly.
+ *
+ * @param opts - Event metadata (command, state, duration, optional error/product/counters)
+ *
+ * @example
+ * ```ts
+ * buildAndSendEvent({
+ *   command: 'deploy',
+ *   state: 'SUCCESS',
+ *   duration: 4500,
+ *   product: { cdkVersion: '2.150.0' },
+ * });
+ * ```
+ */
+export function buildAndSendEvent(opts: BuildAndSendEventOptions): void {
+  try {
+    const filePath = getTelemetryFilePath();
+    const enabled = isTelemetryEnabled();
+    if (!filePath && !enabled) return;
+
+    const event = buildEvent(opts);
+
+    if (filePath) writeToTelemetryFile(event);
+    if (enabled) sendEvent(event);
+  } catch {
+    // Telemetry must never throw or affect the user's command
+  }
+}
+
+/**
+ * Send a pre-built telemetry event to the collection endpoint.
+ *
+ * Fire-and-forget: no retry, 500ms timeout, all errors silently swallowed.
+ * Debug output available via `NODE_DEBUG=blocks-telemetry`.
+ */
+export function sendEvent(event: BlocksTelemetryEvent): void {
+  try {
+    const endpoint = getEndpoint();
+    const payload = JSON.stringify(event);
+
+    // E2E test sink: writes to BLOCKS_TELEMETRY_FILE env path (test-facing, for assertions)
+    if (process.env.BLOCKS_TELEMETRY_FILE) {
+      try { writeFileSync(process.env.BLOCKS_TELEMETRY_FILE, payload); } catch {}
+    }
+
+    debug('sending event to %s (%d bytes)', endpoint, Buffer.byteLength(payload));
+
+    const url = new URL(endpoint);
+    const isHttps = url.protocol === 'https:';
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+
+    const req = requestFn(
+      {
+        hostname: url.hostname,
+        port: url.port || (isHttps ? '443' : '80'),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+        },
+        timeout: TIMEOUT_MS,
+      },
+      (res) => {
+        debug('event sent (status=%d)', res.statusCode);
+        res.resume();
+      },
+    );
+
+    req.on('error', (err) => { debug('send failed: %s', err.message); });
+    req.on('timeout', () => { debug('send timed out'); req.destroy(); });
+    req.write(payload);
+    req.end();
+  } catch {
+    // Telemetry must never throw or affect the user's command
+  }
+}

package/src/telemetry/config-writer.ts

@@ -0,0 +1,52 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+interface TelemetryConfig {
+  enabled?: boolean;
+  projectId?: string;
+  [key: string]: unknown;
+}
+
+interface BlocksConfig {
+  telemetry?: TelemetryConfig;
+  [key: string]: unknown;
+}
+
+/**
+ * Read an existing config file, merge the telemetry.enabled setting, and write it back.
+ * Creates the file and parent directories if they don't exist.
+ * Preserves all other keys in the config file and in the telemetry object
+ * (e.g., projectId).
+ *
+ * Config format:
+ * ```json
+ * { "telemetry": { "enabled": true, "projectId": "..." } }
+ * ```
+ *
+ * @param configPath - Absolute path to the config file
+ * @param telemetryEnabled - Whether telemetry should be enabled
+ */
+export function writeConfigTelemetry(configPath: string, telemetryEnabled: boolean): void {
+  let existing: BlocksConfig = {};
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    existing = JSON.parse(content) as BlocksConfig;
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  const telemetry: TelemetryConfig = (existing.telemetry && typeof existing.telemetry === 'object')
+    ? { ...existing.telemetry }
+    : {};
+
+  telemetry.enabled = telemetryEnabled;
+  existing.telemetry = telemetry;
+
+  const dir = dirname(configPath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+}