@aws-blocks/core 0.1.0

package/dist/redact.js

@@ -0,0 +1,134 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Sensitive-field redaction for logging.
+ *
+ * The dev server logs RPC request/response bodies to help debug cross-stack
+ * wire-format mismatches. Those bodies carry credentials (sign-in passwords,
+ * new-password challenge responses) and bearer-style secrets (Cognito challenge
+ * `session` tokens, MFA shared secrets, OTP codes). Logging them verbatim puts
+ * plaintext passwords and reusable tokens in the log stream. This module masks
+ * those fields before anything is logged, without mutating the value that
+ * actually flows over the wire.
+ *
+ * Two complementary rules, because auth payloads hide secrets two ways:
+ *
+ *  1. **Direct keys** — `{ password: '...', session: '...' }`. Redacted by
+ *     field NAME, matched case-insensitively (substring).
+ *
+ *  2. **Form-field descriptors** — the auth state machine ships secrets as
+ *     `{ name: 'session', defaultValue: '<token>' }` (see
+ *     `@aws-blocks/auth-common` AuthField). Here the secret sits under the
+ *     innocuous key `defaultValue`; the sensitive word is the *value* of a
+ *     sibling `name`. Rule 1 alone would walk straight past it. So when an
+ *     object carries a sensitive `name`, its `defaultValue` is redacted too.
+ *
+ * The wire payload is never altered — only the logged copy is scrubbed.
+ */
+/** The string substituted for any sensitive value. */
+export const REDACTED = '[REDACTED]';
+/**
+ * Field-name fragments whose values must never be logged. Matched
+ * case-insensitively as a SUBSTRING, so prefixed/suffixed variants
+ * (`accessToken`, `refreshToken`, `idToken`, `apiKey`, `clientSecret`) all
+ * match without enumerating every spelling. Keep aligned with the auth action
+ * payloads in `@aws-blocks/auth-common` plus the generic credential vocabulary.
+ */
+const SENSITIVE_KEY_PARTS = [
+    'password',
+    'session',
+    'token',
+    'secret',
+    'credential',
+    'apikey',
+    'authorization',
+];
+/**
+ * Field names that are sensitive only as an EXACT match. The OTP / verification
+ * code the auth state machine sends is literally named `code` (see
+ * `@aws-blocks/auth-common` confirmSignIn payloads). Matching it as a substring
+ * would mask innocuous fields like `statusCode`, `errorCode`, `countryCode`,
+ * `zipCode`, `qrCode` — log noise that defeats the debugging purpose of these
+ * logs without protecting anything. So `code` is exact-match only.
+ */
+const SENSITIVE_KEY_EXACT = new Set(['code']);
+/**
+ * Whether a field name should be redacted: an exact-match against
+ * {@link SENSITIVE_KEY_EXACT}, or a case-insensitive substring match against
+ * {@link SENSITIVE_KEY_PARTS}.
+ */
+function isSensitiveKey(key) {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_KEY_EXACT.has(lower))
+        return true;
+    return SENSITIVE_KEY_PARTS.some((part) => lower.includes(part));
+}
+/**
+ * Return a deep copy of `value` with the value of every sensitive field
+ * replaced by {@link REDACTED}. Arrays and nested objects are walked; the
+ * input is never mutated. Circular references are emitted as `'[Circular]'`.
+ *
+ * Primitives are returned unchanged — only object/array *fields* are matched
+ * against the sensitive-key list, since a bare string has no field name to
+ * key off.
+ *
+ * `seen` tracks the current ancestor PATH, not every node ever visited: each
+ * node is added before its children are walked and removed afterwards. A
+ * plain visited-set would flag the second appearance of a *shared* (non-cyclic)
+ * reference as `'[Circular]'` — e.g. `{ a: shared, b: shared }` — silently
+ * dropping real data from the log. Only a reference still open on the stack is
+ * a genuine cycle.
+ */
+export function redactForLogging(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (seen.has(value)) {
+        return '[Circular]';
+    }
+    seen.add(value);
+    let out;
+    if (Array.isArray(value)) {
+        out = value.map((item) => redactForLogging(item, seen));
+    }
+    else {
+        const obj = value;
+        // Rule 2: form-field descriptor `{ name: <sensitive>, defaultValue: <secret> }`.
+        // The secret hides under `defaultValue` while the sensitive word is the value
+        // of `name` — so the direct-key pass below never sees it. Detect the shape and
+        // redact `defaultValue` explicitly.
+        const masksDefaultValue = typeof obj.name === 'string'
+            && isSensitiveKey(obj.name)
+            && 'defaultValue' in obj;
+        const result = {};
+        for (const [key, val] of Object.entries(obj)) {
+            if (isSensitiveKey(key) || (key === 'defaultValue' && masksDefaultValue)) {
+                // Preserve presence/absence so logs still show the field was sent,
+                // without revealing it. Skip masking explicit null/undefined so an
+                // absent secret doesn't look like a populated one.
+                result[key] = val === null || val === undefined ? val : REDACTED;
+            }
+            else {
+                result[key] = redactForLogging(val, seen);
+            }
+        }
+        out = result;
+    }
+    // Pop this node off the ancestor path now that its subtree is fully walked,
+    // so sibling branches can reference the same object without false `[Circular]`.
+    seen.delete(value);
+    return out;
+}
+/**
+ * Convenience for log call sites: redact `value` and serialize it to a JSON
+ * string. Returns a safe placeholder instead of throwing if serialization
+ * fails (e.g. a BigInt slips through), so logging can never crash a request.
+ */
+export function redactToJson(value) {
+    try {
+        return JSON.stringify(redactForLogging(value));
+    }
+    catch {
+        return '[unserializable]';
+    }
+}

package/dist/redact.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redact.test.d.ts.map

package/dist/redact.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.test.d.ts","sourceRoot":"","sources":["../src/redact.test.ts"],"names":[],"mappings":""}

package/dist/redact.test.js

@@ -0,0 +1,199 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { redactForLogging, redactToJson, REDACTED } from './redact.js';
+describe('redactForLogging', () => {
+    it('redacts a top-level password field', () => {
+        const out = redactForLogging({ username: 'alice', password: 'hunter2' });
+        assert.deepEqual(out, { username: 'alice', password: REDACTED });
+    });
+    it('redacts every sensitive credential/token field name', () => {
+        const out = redactForLogging({
+            password: 'p',
+            newPassword: 'np',
+            session: 's',
+            accessToken: 'at',
+            refreshToken: 'rt',
+            idToken: 'it',
+            sharedSecret: 'ss',
+            clientSecret: 'cs',
+            apiKey: 'ak',
+            authorization: 'Bearer x',
+            code: '123456',
+            credentials: 'c',
+        });
+        for (const v of Object.values(out)) {
+            assert.equal(v, REDACTED);
+        }
+    });
+    it('matches field names case-insensitively', () => {
+        const out = redactForLogging({ PassWord: 'x', SESSION: 'y' });
+        assert.equal(out.PassWord, REDACTED);
+        assert.equal(out.SESSION, REDACTED);
+    });
+    it('leaves non-sensitive fields untouched', () => {
+        const input = { username: 'bob', email: 'b@example.com', count: 3, ok: true };
+        assert.deepEqual(redactForLogging(input), input);
+    });
+    it('walks nested objects', () => {
+        const out = redactForLogging({
+            action: 'confirmSignIn',
+            payload: { session: 'tok', code: '999' },
+        });
+        assert.deepEqual(out, {
+            action: 'confirmSignIn',
+            payload: { session: REDACTED, code: REDACTED },
+        });
+    });
+    it('walks arrays (e.g. positional RPC args)', () => {
+        const out = redactForLogging([
+            { action: 'signIn', username: 'a', password: 'secret' },
+            { action: 'confirmSignIn', session: 'tok', code: '111' },
+        ]);
+        assert.deepEqual(out, [
+            { action: 'signIn', username: 'a', password: REDACTED },
+            { action: 'confirmSignIn', session: REDACTED, code: REDACTED },
+        ]);
+    });
+    it('preserves null/undefined sensitive fields without masking', () => {
+        const out = redactForLogging({ password: null, session: undefined });
+        assert.equal(out.password, null);
+        assert.equal(out.session, undefined);
+    });
+    it('returns primitives unchanged', () => {
+        assert.equal(redactForLogging('just a string'), 'just a string');
+        assert.equal(redactForLogging(42), 42);
+        assert.equal(redactForLogging(null), null);
+    });
+    it('does not mutate the input object', () => {
+        const input = { password: 'keep-me', username: 'alice' };
+        redactForLogging(input);
+        assert.equal(input.password, 'keep-me');
+    });
+    // Regression: the auth state machine ships secrets as form-field
+    // descriptors `{ name: 'session', defaultValue: '<token>' }`. The secret
+    // sits under `defaultValue`, NOT under a key literally named `session`, so
+    // plain key-name redaction walks past it. These guard the descriptor branch.
+    it('redacts defaultValue of a sensitive AuthField descriptor', () => {
+        const out = redactForLogging({
+            name: 'session',
+            label: 'Session',
+            type: 'hidden',
+            defaultValue: 'COGNITO_SESSION_TOKEN',
+        });
+        assert.equal(out.name, 'session');
+        assert.equal(out.defaultValue, REDACTED);
+    });
+    it('redacts session + sharedSecret in a full confirmingSignIn AuthState', () => {
+        const authState = {
+            state: 'confirmingSignIn',
+            actions: [{
+                    name: 'confirmSignIn',
+                    label: 'Set Up Authenticator',
+                    fields: [
+                        { name: 'session', label: 'Session', type: 'hidden', required: true, defaultValue: 'SESSION_TOKEN_abc' },
+                        { name: 'sharedSecret', label: 'Shared Secret', type: 'hidden', required: true, defaultValue: 'JBSWY3DPEHPK3PXP' },
+                        { name: 'code', label: 'Code', type: 'text', required: true },
+                    ],
+                }],
+        };
+        const json = JSON.stringify(redactForLogging(authState));
+        assert.ok(!json.includes('SESSION_TOKEN_abc'), 'session token must not leak');
+        assert.ok(!json.includes('JBSWY3DPEHPK3PXP'), 'TOTP shared secret must not leak');
+        // Non-secret descriptor fields are preserved for debuggability.
+        assert.ok(json.includes('confirmSignIn'));
+        assert.ok(json.includes('Set Up Authenticator'));
+    });
+    it('leaves defaultValue untouched for a non-sensitive field (e.g. echoed username)', () => {
+        const out = redactForLogging({
+            name: 'username',
+            type: 'hidden',
+            defaultValue: 'alice',
+        });
+        assert.equal(out.defaultValue, 'alice');
+    });
+    it('handles circular references', () => {
+        const a = { username: 'alice' };
+        a.self = a;
+        const out = redactForLogging(a);
+        assert.equal(out.username, 'alice');
+        assert.equal(out.self, '[Circular]');
+    });
+    it('detects cycles nested deeper than the root', () => {
+        const root = { level: 1 };
+        const child = { level: 2, parent: root };
+        root.child = child;
+        const out = redactForLogging(root);
+        assert.equal(out.child.level, 2);
+        assert.equal(out.child.parent, '[Circular]');
+    });
+    // Regression: `seen` must track the ancestor PATH, not every node ever
+    // visited. A shared (non-cyclic) reference reached twice via sibling
+    // branches must be emitted in full both times — a visited-set would wrongly
+    // flag the second one as '[Circular]' and drop real data from the log.
+    it('does not flag shared (non-circular) references as circular', () => {
+        const shared = { region: 'us-east-1', count: 2 };
+        const out = redactForLogging({ a: shared, b: shared });
+        assert.deepEqual(out.a, shared);
+        assert.deepEqual(out.b, shared);
+    });
+    it('emits a shared reference repeated in an array, not [Circular]', () => {
+        const shared = { id: 'x' };
+        const out = redactForLogging([shared, shared, shared]);
+        assert.deepEqual(out, [shared, shared, shared]);
+    });
+    it('still redacts secrets inside a shared reference each time', () => {
+        const shared = { username: 'u', password: 'secret' };
+        const out = redactForLogging({ first: shared, second: shared });
+        assert.equal(out.first.password, REDACTED);
+        assert.equal(out.second.password, REDACTED);
+        assert.equal(out.second.username, 'u');
+    });
+    // Regression: `code` is exact-match only, so substring siblings like
+    // statusCode/errorCode stay visible — they carry no secret and masking them
+    // defeats the debugging purpose of the logs.
+    it('redacts an exact `code` field but not `code`-substring fields', () => {
+        const out = redactForLogging({
+            code: '123456',
+            statusCode: 200,
+            errorCode: 'E_BAD',
+            countryCode: 'US',
+            zipCode: '98101',
+            qrCode: 'data:image/png',
+        });
+        assert.equal(out.code, REDACTED);
+        assert.equal(out.statusCode, 200);
+        assert.equal(out.errorCode, 'E_BAD');
+        assert.equal(out.countryCode, 'US');
+        assert.equal(out.zipCode, '98101');
+        assert.equal(out.qrCode, 'data:image/png');
+    });
+});
+describe('redactToJson', () => {
+    it('serializes a redacted copy', () => {
+        const json = redactToJson({ username: 'alice', password: 'hunter2' });
+        assert.equal(json, JSON.stringify({ username: 'alice', password: REDACTED }));
+    });
+    it('returns a safe placeholder on serialization failure', () => {
+        // BigInt is not JSON-serializable and survives redaction (not a sensitive key).
+        assert.equal(redactToJson({ big: 10n }), '[unserializable]');
+    });
+    it('does not leak secrets even when truncation would apply downstream', () => {
+        const json = redactToJson([{ action: 'signIn', username: 'u', password: 'p'.repeat(50) }]);
+        assert.ok(!json.includes('pppp'));
+        assert.ok(json.includes(REDACTED));
+    });
+    it('redacts secrets in a real JSON-RPC request body shape', () => {
+        const body = {
+            jsonrpc: '2.0',
+            method: 'authApi.setAuthState',
+            params: [{ action: 'signIn', username: 'a', password: 'hunter2' }],
+            id: 1,
+        };
+        const json = redactToJson(body);
+        assert.ok(!json.includes('hunter2'));
+        assert.ok(json.includes(REDACTED));
+        assert.ok(json.includes('setAuthState'), 'method name preserved for debugging');
+    });
+});

package/dist/rpc.d.ts

@@ -0,0 +1,54 @@
+/** The pieces every server-side handler needs after parsing a request. */
+export interface RpcParsedRequest {
+    apiNamespace: string;
+    method: string;
+    /** Positional args — from array params directly, or Object.values() of named params. */
+    args: unknown[];
+    id: string | number | null;
+}
+/** Discriminated union returned by `parseRpcRequest`. */
+export type RpcParseResult = {
+    ok: true;
+    request: RpcParsedRequest;
+} | {
+    ok: false;
+    response: string;
+};
+/** Reserved JSON-RPC error codes. */
+export declare const RpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** Build a JSON-RPC 2.0 request body string ready to POST. */
+export declare function encodeRpcRequest(apiNamespace: string, method: string, args: unknown[]): string;
+/**
+ * Decode a JSON-RPC 2.0 response body.
+ *
+ * Returns the `result` on success, or throws an `ApiError` on error.
+ */
+export declare function decodeRpcResponse(body: unknown): unknown;
+/**
+ * Parse a raw body string into a validated `RpcParsedRequest`.
+ *
+ * Returns `{ ok: false, response }` with a ready-to-send JSON string when
+ * the request is malformed, so callers can short-circuit without knowing
+ * anything about the JSON-RPC spec.
+ */
+export declare function parseRpcRequest(bodyText: string): RpcParseResult;
+/** Encode a successful result as a JSON-RPC 2.0 response string. */
+export declare function successResponse(result: unknown, id: string | number | null): string;
+/**
+ * Encode an error as a JSON-RPC 2.0 response string.
+ *
+ * For `ApiError` instances the HTTP status becomes the error code (positive
+ * integers never collide with the reserved -32xxx range). Generic errors
+ * use code 500.
+ */
+export declare function errorResponseFromCatch(error: unknown, id: string | number | null): string;
+/** Encode a "method not found" error. */
+export declare function methodNotFoundResponse(detail: string, id: string | number | null): string;
+export declare function errorResponse(code: number, message: string, id: string | number | null, data?: Record<string, unknown>): string;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAgBA,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,yDAAyD;AACzD,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAMpC,qCAAqC;AACrC,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAMX,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAO9F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAiBxD;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CA0ChE;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAOzF;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAEzF;AAID,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAC1B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAMR"}

package/dist/rpc.js

@@ -0,0 +1,127 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * JSON-RPC 2.0 wire format — single source of truth.
+ *
+ * All encoding/decoding of the Blocks RPC protocol lives here so that the
+ * client, Lambda handler, and dev server never deal with the spec directly.
+ *
+ * @see https://www.jsonrpc.org/specification
+ */
+import { ApiError } from './errors.js';
+// ── Constants ───────────────────────────────────────────────────────────────
+const VERSION = '2.0';
+/** Reserved JSON-RPC error codes. */
+export const RpcErrorCode = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+};
+// ── Client helpers (encode request, decode response) ────────────────────────
+let _nextId = 1;
+/** Build a JSON-RPC 2.0 request body string ready to POST. */
+export function encodeRpcRequest(apiNamespace, method, args) {
+    return JSON.stringify({
+        jsonrpc: VERSION,
+        method: `${apiNamespace}.${method}`,
+        params: args,
+        id: _nextId++,
+    });
+}
+/**
+ * Decode a JSON-RPC 2.0 response body.
+ *
+ * Returns the `result` on success, or throws an `ApiError` on error.
+ */
+export function decodeRpcResponse(body) {
+    const rpc = body;
+    if (rpc.error) {
+        const { code, message, data } = rpc.error;
+        // Application error codes use the HTTP status directly (e.g. 409).
+        // Reserved JSON-RPC codes (-32xxx) map to 500.
+        const status = code > 0 ? code : 500;
+        throw new ApiError(message, status, {
+            ...(data?.name ? { name: data.name } : {}),
+            ...(data?.retriable === true ? { retriable: true } : {}),
+        });
+    }
+    return rpc.result;
+}
+// ── Server helpers (parse request, encode response) ─────────────────────────
+/**
+ * Parse a raw body string into a validated `RpcParsedRequest`.
+ *
+ * Returns `{ ok: false, response }` with a ready-to-send JSON string when
+ * the request is malformed, so callers can short-circuit without knowing
+ * anything about the JSON-RPC spec.
+ */
+export function parseRpcRequest(bodyText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText || '{}');
+    }
+    catch {
+        return { ok: false, response: errorResponse(RpcErrorCode.ParseError, 'Parse error', null) };
+    }
+    const id = parsed.id ?? null;
+    if (parsed.jsonrpc !== VERSION || typeof parsed.method !== 'string') {
+        return {
+            ok: false,
+            response: errorResponse(RpcErrorCode.InvalidRequest, 'Invalid Request: expected JSON-RPC 2.0 — {"jsonrpc":"2.0","method":"namespace.method","params":[...],"id":1}', id, { name: 'InvalidRequest' }),
+        };
+    }
+    const dotIndex = parsed.method.indexOf('.');
+    if (dotIndex === -1) {
+        return {
+            ok: false,
+            response: errorResponse(RpcErrorCode.InvalidRequest, 'Invalid Request: method must be "namespace.method"', id, { name: 'InvalidRequest' }),
+        };
+    }
+    return {
+        ok: true,
+        request: {
+            apiNamespace: parsed.method.substring(0, dotIndex),
+            method: parsed.method.substring(dotIndex + 1),
+            // JSON-RPC 2.0 §4.2: params may be an array (positional) or object (named).
+            args: Array.isArray(parsed.params)
+                ? parsed.params
+                : Object.values(parsed.params ?? {}),
+            id,
+        },
+    };
+}
+/** Encode a successful result as a JSON-RPC 2.0 response string. */
+export function successResponse(result, id) {
+    return JSON.stringify({ jsonrpc: VERSION, result, id });
+}
+/**
+ * Encode an error as a JSON-RPC 2.0 response string.
+ *
+ * For `ApiError` instances the HTTP status becomes the error code (positive
+ * integers never collide with the reserved -32xxx range). Generic errors
+ * use code 500.
+ */
+export function errorResponseFromCatch(error, id) {
+    const code = error instanceof ApiError ? error.status : 500;
+    const message = error instanceof Error ? error.message : String(error);
+    const data = {};
+    if (error instanceof Error && error.name && error.name !== 'Error')
+        data.name = error.name;
+    if (error instanceof ApiError && error.retriable)
+        data.retriable = true;
+    return errorResponse(code, message, id, Object.keys(data).length > 0 ? data : undefined);
+}
+/** Encode a "method not found" error. */
+export function methodNotFoundResponse(detail, id) {
+    return errorResponse(RpcErrorCode.MethodNotFound, `Method not found: ${detail}`, id);
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+export function errorResponse(code, message, id, data) {
+    return JSON.stringify({
+        jsonrpc: VERSION,
+        error: { code, message, ...(data ? { data } : {}) },
+        id,
+    });
+}

package/dist/rpc.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rpc.test.d.ts.map

package/dist/rpc.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.test.d.ts","sourceRoot":"","sources":["../src/rpc.test.ts"],"names":[],"mappings":""}

package/dist/rpc.test.js

@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseRpcRequest, RpcErrorCode } from './rpc.js';
+describe('-32600 Invalid Request error shape', () => {
+    it('returns proper JSON-RPC 2.0 envelope with error code', () => {
+        const result = parseRpcRequest(JSON.stringify({ method: 'ns.method', id: 1 }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.jsonrpc, '2.0');
+            assert.strictEqual(parsed.error.code, RpcErrorCode.InvalidRequest);
+            assert.strictEqual(parsed.id, 1);
+        }
+    });
+    it('includes descriptive message with expected JSON-RPC 2.0 shape', () => {
+        const result = parseRpcRequest(JSON.stringify({ method: 'test', id: 1 }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.ok(parsed.error.message.includes('expected JSON-RPC 2.0'), `message should describe the expected format, got: ${parsed.error.message}`);
+            assert.ok(parsed.error.message.includes('"jsonrpc":"2.0"'), `message should echo the expected envelope shape`);
+        }
+    });
+    it('includes data.name per D-003 convention', () => {
+        const result = parseRpcRequest(JSON.stringify({ method: 'test', id: 1 }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.error.data.name, 'InvalidRequest');
+        }
+    });
+    it('preserves the caller id in the error response', () => {
+        const result = parseRpcRequest(JSON.stringify({ id: 'abc-123' }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.id, 'abc-123');
+        }
+    });
+    it('uses null id when request omits id', () => {
+        const result = parseRpcRequest(JSON.stringify({ jsonrpc: '1.0', method: 123 }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.id, null);
+        }
+    });
+    it('includes data.name when method lacks namespace dot separator', () => {
+        const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'noNamespace', id: 7 }));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.error.code, RpcErrorCode.InvalidRequest);
+            assert.strictEqual(parsed.error.data.name, 'InvalidRequest');
+            assert.strictEqual(parsed.id, 7);
+        }
+    });
+});

package/dist/scripts/cdk-telemetry-env.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build CDK CLI telemetry-related environment variables.
+ *
+ * When Blocks telemetry is enabled, sets `CDK_CLI_USERAGENT` so the CDK CLI
+ * attributes usage back to Blocks. When telemetry is disabled (user opted out),
+ * sets `CDK_DISABLE_CLI_TELEMETRY=1` to suppress CDK's own telemetry collection
+ * and omits the user-agent string.
+ *
+ * @param command - The Blocks command context (e.g. "sandbox", "production")
+ * @returns An object to spread into the child process `env`
+ */
+export declare function getCdkTelemetryEnv(command: string): Record<string, string>;
+//# sourceMappingURL=cdk-telemetry-env.d.ts.map

package/dist/scripts/cdk-telemetry-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-telemetry-env.d.ts","sourceRoot":"","sources":["../../src/scripts/cdk-telemetry-env.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK1E"}

package/dist/scripts/cdk-telemetry-env.js

@@ -0,0 +1,21 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { isTelemetryEnabled } from '../telemetry/consent.js';
+import { CORE_VERSION } from '../version.js';
+/**
+ * Build CDK CLI telemetry-related environment variables.
+ *
+ * When Blocks telemetry is enabled, sets `CDK_CLI_USERAGENT` so the CDK CLI
+ * attributes usage back to Blocks. When telemetry is disabled (user opted out),
+ * sets `CDK_DISABLE_CLI_TELEMETRY=1` to suppress CDK's own telemetry collection
+ * and omits the user-agent string.
+ *
+ * @param command - The Blocks command context (e.g. "sandbox", "production")
+ * @returns An object to spread into the child process `env`
+ */
+export function getCdkTelemetryEnv(command) {
+    if (!isTelemetryEnabled()) {
+        return { CDK_DISABLE_CLI_TELEMETRY: '1' };
+    }
+    return { CDK_CLI_USERAGENT: `aws-blocks/${CORE_VERSION}/${command}` };
+}

package/dist/scripts/cdk-telemetry-env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cdk-telemetry-env.test.d.ts.map

package/dist/scripts/cdk-telemetry-env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-telemetry-env.test.d.ts","sourceRoot":"","sources":["../../src/scripts/cdk-telemetry-env.test.ts"],"names":[],"mappings":""}