@aws-blocks/core 0.1.0

package/src/scripts/validate-spec.ts

@@ -0,0 +1,199 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Validate a generated OpenRPC document for structural conformance.
+ *
+ * Checks:
+ * - Required top-level fields (openrpc, info, methods)
+ * - OpenRPC version format
+ * - Method structure (name, params, result)
+ * - Param structure (name, required, schema)
+ * - Result structure (name, schema)
+ * - All $ref pointers resolve to entries in components.schemas
+ * - No `nullable` field (should use oneOf with null instead)
+ * - Method names are namespace-qualified (contain a dot)
+ * - Result names are descriptive (not just "result")
+ *
+ * Returns an array of error messages. Empty array = valid.
+ */
+
+export interface SpecValidationError {
+	path: string;
+	message: string;
+}
+
+export function validateSpec(doc: any): SpecValidationError[] {
+	const errors: SpecValidationError[] = [];
+
+	// Top-level required fields
+	if (!doc || typeof doc !== 'object') {
+		return [{ path: '', message: 'Document must be an object' }];
+	}
+
+	if (typeof doc.openrpc !== 'string') {
+		errors.push({ path: 'openrpc', message: 'Missing or invalid "openrpc" version string' });
+	} else if (!/^\d+\.\d+\.\d+$/.test(doc.openrpc)) {
+		errors.push({ path: 'openrpc', message: `Invalid version format: "${doc.openrpc}"` });
+	}
+
+	if (!doc.info || typeof doc.info !== 'object') {
+		errors.push({ path: 'info', message: 'Missing "info" object' });
+	} else {
+		if (typeof doc.info.title !== 'string') {
+			errors.push({ path: 'info.title', message: 'Missing "info.title" string' });
+		}
+		if (typeof doc.info.version !== 'string') {
+			errors.push({ path: 'info.version', message: 'Missing "info.version" string' });
+		}
+	}
+
+	if (!Array.isArray(doc.methods)) {
+		errors.push({ path: 'methods', message: 'Missing "methods" array' });
+		return errors;
+	}
+
+	// Collect known schema names for $ref resolution
+	const knownSchemas = new Set<string>(
+		Object.keys(doc.components?.schemas || {})
+	);
+
+	// Scan entire document for $ref pointers and nullable fields
+	const docStr = JSON.stringify(doc);
+	if (docStr.includes('"nullable"')) {
+		errors.push({
+			path: '',
+			message: 'Document contains "nullable" field — use oneOf with { type: "null" } instead',
+		});
+	}
+
+	// Validate each method
+	for (let i = 0; i < doc.methods.length; i++) {
+		const method = doc.methods[i];
+		const mp = `methods[${i}]`;
+
+		if (typeof method.name !== 'string') {
+			errors.push({ path: `${mp}.name`, message: 'Missing method name' });
+			continue;
+		}
+
+		const mpath = `methods["${method.name}"]`;
+
+		// Namespace-qualified check
+		if (!method.name.includes('.')) {
+			errors.push({ path: `${mpath}.name`, message: `Method name "${method.name}" is not namespace-qualified (expected "namespace.method")` });
+		}
+
+		// Params
+		if (!Array.isArray(method.params)) {
+			errors.push({ path: `${mpath}.params`, message: 'Missing "params" array' });
+		} else {
+			for (let j = 0; j < method.params.length; j++) {
+				const param = method.params[j];
+				const pp = `${mpath}.params[${j}]`;
+				if (typeof param.name !== 'string') {
+					errors.push({ path: pp, message: 'Missing param name' });
+				}
+				if (typeof param.required !== 'boolean') {
+					errors.push({ path: `${pp}.required`, message: 'Missing or non-boolean "required"' });
+				}
+				if (!param.schema || typeof param.schema !== 'object') {
+					errors.push({ path: `${pp}.schema`, message: 'Missing param schema' });
+				}
+				// Check $ref resolution
+				if (param.schema?.$ref) {
+					validateRef(param.schema.$ref, `${pp}.schema.$ref`, knownSchemas, errors);
+				}
+			}
+		}
+
+		// Result
+		if (!method.result || typeof method.result !== 'object') {
+			errors.push({ path: `${mpath}.result`, message: 'Missing "result" object' });
+		} else {
+			if (typeof method.result.name !== 'string') {
+				errors.push({ path: `${mpath}.result.name`, message: 'Missing result name' });
+			} else if (method.result.name === 'result') {
+				errors.push({ path: `${mpath}.result.name`, message: 'Result name should be descriptive, not "result"' });
+			}
+			if (!method.result.schema || typeof method.result.schema !== 'object') {
+				errors.push({ path: `${mpath}.result.schema`, message: 'Missing result schema' });
+			}
+			// Check $ref resolution
+			if (method.result.schema?.$ref) {
+				validateRef(method.result.schema.$ref, `${mpath}.result.schema.$ref`, knownSchemas, errors);
+			}
+			// Check oneOf members for $refs
+			if (Array.isArray(method.result.schema?.oneOf)) {
+				for (let k = 0; k < method.result.schema.oneOf.length; k++) {
+					const member = method.result.schema.oneOf[k];
+					if (member.$ref) {
+						validateRef(member.$ref, `${mpath}.result.schema.oneOf[${k}].$ref`, knownSchemas, errors);
+					}
+				}
+			}
+
+			// Validate x-blocks-transferable extension field
+			if ('x-blocks-transferable' in (method.result.schema ?? {})) {
+				const blocksTag = method.result.schema['x-blocks-transferable'];
+				if (typeof blocksTag !== 'string' || blocksTag.length === 0) {
+					errors.push({
+						path: `${mpath}.result.schema.x-blocks-transferable`,
+						message: 'x-blocks-transferable must be a non-empty string',
+					});
+				}
+			}
+
+			// Validate x-blocks-type-args extension field
+			if ('x-blocks-type-args' in (method.result.schema ?? {})) {
+				const typeArgs = method.result.schema['x-blocks-type-args'];
+				if (!Array.isArray(typeArgs)) {
+					errors.push({
+						path: `${mpath}.result.schema.x-blocks-type-args`,
+						message: 'x-blocks-type-args must be an array of JSON Schema objects',
+					});
+				} else {
+					for (let k = 0; k < typeArgs.length; k++) {
+						const arg = typeArgs[k];
+						if (!arg || typeof arg !== 'object' || Array.isArray(arg)) {
+							errors.push({
+								path: `${mpath}.result.schema.x-blocks-type-args[${k}]`,
+								message: 'Each entry in x-blocks-type-args must be a valid JSON Schema object',
+							});
+						} else if (arg.$ref) {
+							validateRef(arg.$ref, `${mpath}.result.schema.x-blocks-type-args[${k}].$ref`, knownSchemas, errors);
+						}
+					}
+				}
+			}
+		}
+	}
+
+	// Validate components.schemas entries are well-formed
+	if (doc.components?.schemas) {
+		for (const [name, schema] of Object.entries(doc.components.schemas)) {
+			if (!schema || typeof schema !== 'object') {
+				errors.push({ path: `components.schemas.${name}`, message: 'Schema must be an object' });
+			}
+		}
+	}
+
+	return errors;
+}
+
+function validateRef(
+	ref: string,
+	path: string,
+	knownSchemas: Set<string>,
+	errors: SpecValidationError[],
+): void {
+	const prefix = '#/components/schemas/';
+	if (!ref.startsWith(prefix)) {
+		errors.push({ path, message: `$ref "${ref}" must start with "${prefix}"` });
+		return;
+	}
+	const schemaName = ref.slice(prefix.length);
+	if (!knownSchemas.has(schemaName)) {
+		errors.push({ path, message: `$ref "${ref}" does not resolve — "${schemaName}" not found in components.schemas` });
+	}
+}

package/src/server/index.ts

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export { withAuth, registerCookieProvider, clearCookieProviders } from './withAuth.js';
+export type { CookieProvider } from './withAuth.js';

package/src/server/withAuth.test.ts

@@ -0,0 +1,348 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getContext } from 'unctx';
+import { withAuth, registerCookieProvider, clearCookieProviders } from './index.js';
+import { _getProviders } from './withAuth.js';
+import { ApiError } from '../errors.js';
+
+// Seed the `nitro-app` unctx context with `asyncContext: true` at module load,
+// mirroring Nitro's `experimental.asyncContext: true`. unctx caches the context
+// instance on first `getContext()` call (first-write-wins), so this MUST run
+// before any test triggers the provider — otherwise a non-async instance gets
+// cached and `.use()` cannot survive the provider's internal `await import`.
+getContext('nitro-app', { asyncContext: true, AsyncLocalStorage });
+
+describe('withAuth', () => {
+  let originalStore: any;
+
+  beforeEach(() => {
+    originalStore = (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+  });
+
+  afterEach(() => {
+    if (originalStore === undefined) {
+      delete (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+    } else {
+      (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = originalStore;
+    }
+  });
+
+  test('forwards explicit cookies via AsyncLocalStorage', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    let captured: string | undefined;
+    await withAuth(async () => {
+      captured = store.getStore();
+      return 'result';
+    }, 'session=abc123; token=xyz');
+
+    assert.strictEqual(captured, 'session=abc123; token=xyz');
+  });
+
+  test('returns the value from fn when explicit cookies provided', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    const result = await withAuth(async () => {
+      return { data: 42 };
+    }, 'session=abc');
+
+    assert.deepStrictEqual(result, { data: 42 });
+  });
+
+  test('uses existing AsyncLocalStorage context when already set', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    let innerCookies: string | undefined;
+
+    await store.run('existing-cookies', async () => {
+      const result = await withAuth(async () => {
+        innerCookies = store.getStore();
+        return 'ok';
+      });
+      assert.strictEqual(result, 'ok');
+    });
+
+    assert.strictEqual(innerCookies, 'existing-cookies');
+  });
+
+  test('throws when no cookies found and no framework detected', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    const saved = _getProviders().slice();
+    clearCookieProviders();
+
+    try {
+      await assert.rejects(
+        () => withAuth(async () => 'should not reach'),
+        (err: ApiError) => {
+          assert.ok(err instanceof ApiError);
+          assert.ok(err.message.includes('withAuth: No authentication cookies found'));
+          assert.strictEqual(err.status, 401);
+          return true;
+        },
+      );
+    } finally {
+      for (const p of saved) registerCookieProvider(p.name, p.detect);
+    }
+  });
+
+  test('creates AsyncLocalStorage lazily if globalThis store is missing', async () => {
+    delete (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+
+    let storeExistedDuringCall = false;
+    const result = await withAuth(async () => {
+      storeExistedDuringCall = !!(globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+      return 'created';
+    }, 'lazy-cookies');
+
+    assert.strictEqual(result, 'created');
+    assert.ok(storeExistedDuringCall, 'Store should be created lazily');
+    assert.ok((globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__, 'Store should persist on globalThis');
+  });
+
+  test('propagates errors from fn', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    await assert.rejects(
+      () => withAuth(async () => {
+        throw new Error('inner error');
+      }, 'some-cookies'),
+      { message: 'inner error' },
+    );
+  });
+
+  test('multiple nested API calls share the same cookie context', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    const captured: string[] = [];
+
+    await withAuth(async () => {
+      captured.push(store.getStore() ?? 'none');
+      await Promise.resolve();
+      captured.push(store.getStore() ?? 'none');
+      return captured;
+    }, 'shared-session=1');
+
+    assert.deepStrictEqual(captured, ['shared-session=1', 'shared-session=1']);
+  });
+});
+
+describe('Cookie Provider Registry', () => {
+  let originalStore: any;
+  let savedProviders: Array<{ name: string; detect: () => Promise<string | undefined> }>;
+
+  beforeEach(() => {
+    originalStore = (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+    savedProviders = _getProviders().slice();
+    clearCookieProviders();
+  });
+
+  afterEach(() => {
+    clearCookieProviders();
+    for (const p of savedProviders) registerCookieProvider(p.name, p.detect);
+
+    if (originalStore === undefined) {
+      delete (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__;
+    } else {
+      (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = originalStore;
+    }
+  });
+
+  test('default Next.js provider is registered on module load', () => {
+    const providers = savedProviders;
+    const nextProvider = providers.find(p => p.name === 'nextjs');
+    assert.ok(nextProvider, 'Next.js provider should be registered by default');
+  });
+
+  test('Next.js provider returns undefined when next/headers is not available', async () => {
+    const nextProvider = savedProviders.find(p => p.name === 'nextjs');
+    assert.ok(nextProvider);
+
+    const result = await nextProvider.detect();
+    assert.strictEqual(result, undefined);
+  });
+
+  test('default Nuxt provider is registered on module load', () => {
+    const providers = savedProviders;
+    const nuxtProvider = providers.find(p => p.name === 'nuxt');
+    assert.ok(nuxtProvider, 'Nuxt provider should be registered by default');
+  });
+
+  test('Nuxt provider returns undefined cleanly when no Nitro context is bound', async () => {
+    // When the test runs in a plain node env (no Nitro), either `unctx`
+    // isn't installed (import fails) or it is, but `getContext('nitro-app').use()`
+    // throws because no async context is bound. Both paths must return
+    // undefined, and neither should leak the underlying error to the caller.
+    const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+    assert.ok(nuxtProvider);
+
+    // Suppress the one-time console.warn on the asyncContext-disabled path so
+    // it doesn't contaminate test output.
+    process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN = '1';
+    try {
+      const result = await nuxtProvider.detect();
+      assert.strictEqual(result, undefined);
+    } finally {
+      delete process.env.BLOCKS_SUPPRESS_NUXT_ASYNC_CONTEXT_WARN;
+    }
+  });
+
+  test('Nuxt provider reads cookie from the h3 `{ event }` shape (Nitro v2)', async () => {
+    const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+    assert.ok(nuxtProvider);
+
+    // The `nitro-app` context is seeded with asyncContext at module load, so
+    // the binding survives the provider's internal `await import('unctx')`.
+    // Nitro v2 (h3): `{ event }` carrying the cookie on the Node request headers.
+    const bound = { event: { node: { req: { headers: { cookie: 'session=h3' } } } } };
+    const result = await getContext('nitro-app').callAsync(bound, () => nuxtProvider.detect());
+    assert.strictEqual(result, 'session=h3');
+  });
+
+  test('Nuxt provider reads cookie from the srvx `{ request }` shape (Nitro v3 / Nuxt 5)', async () => {
+    const nuxtProvider = savedProviders.find(p => p.name === 'nuxt');
+    assert.ok(nuxtProvider);
+
+    // Nitro v3 (srvx): `{ request }` carrying the cookie on a standard Web
+    // `Request`. This is the forward-compat path guarded by the TODO in
+    // withAuth.ts.
+    const bound = { request: new Request('https://example.com', { headers: { cookie: 'session=srvx' } }) };
+    const result = await getContext('nitro-app').callAsync(bound, () => nuxtProvider.detect());
+    assert.strictEqual(result, 'session=srvx');
+  });
+
+  test('custom provider registration works', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    registerCookieProvider('custom', async () => 'custom-cookie=hello');
+
+    let captured: string | undefined;
+    await withAuth(async () => {
+      captured = store.getStore();
+      return 'ok';
+    });
+
+    assert.strictEqual(captured, 'custom-cookie=hello');
+  });
+
+  test('multiple providers tried in registration order — first match wins', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    const callOrder: string[] = [];
+
+    registerCookieProvider('first', async () => {
+      callOrder.push('first');
+      return undefined;
+    });
+
+    registerCookieProvider('second', async () => {
+      callOrder.push('second');
+      return 'winner=second';
+    });
+
+    registerCookieProvider('third', async () => {
+      callOrder.push('third');
+      return 'should-not-reach=true';
+    });
+
+    let captured: string | undefined;
+    await withAuth(async () => {
+      captured = store.getStore();
+      return 'ok';
+    });
+
+    assert.strictEqual(captured, 'winner=second');
+    assert.deepStrictEqual(callOrder, ['first', 'second']);
+  });
+
+  test('explicit cookies take priority over providers', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    let providerCalled = false;
+    registerCookieProvider('should-not-run', async () => {
+      providerCalled = true;
+      return 'provider-cookie=value';
+    });
+
+    let captured: string | undefined;
+    await withAuth(async () => {
+      captured = store.getStore();
+      return 'ok';
+    }, 'explicit-cookie=priority');
+
+    assert.strictEqual(captured, 'explicit-cookie=priority');
+    assert.strictEqual(providerCalled, false, 'Provider should not be called when explicit cookies given');
+  });
+
+  test('existing ALS context takes priority over providers', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    let providerCalled = false;
+    registerCookieProvider('should-not-run', async () => {
+      providerCalled = true;
+      return 'provider-cookie=value';
+    });
+
+    let captured: string | undefined;
+    await store.run('als-cookies', async () => {
+      await withAuth(async () => {
+        captured = store.getStore();
+        return 'ok';
+      });
+    });
+
+    assert.strictEqual(captured, 'als-cookies');
+    assert.strictEqual(providerCalled, false, 'Provider should not be called when ALS context exists');
+  });
+
+  test('throws when all providers return undefined', async () => {
+    const store = new AsyncLocalStorage<string>();
+    (globalThis as any).__BLOCKS_REQUEST_COOKIES_STORE__ = store;
+
+    registerCookieProvider('nope1', async () => undefined);
+    registerCookieProvider('nope2', async () => undefined);
+
+    await assert.rejects(
+      () => withAuth(async () => 'should not reach'),
+      (err: ApiError) => {
+        assert.ok(err instanceof ApiError);
+        assert.ok(err.message.includes('withAuth: No authentication cookies found'));
+        assert.strictEqual(err.status, 401);
+        return true;
+      },
+    );
+  });
+
+  test('registerCookieProvider appends to existing providers', () => {
+    registerCookieProvider('a', async () => undefined);
+    registerCookieProvider('b', async () => undefined);
+
+    const providers = _getProviders();
+    assert.strictEqual(providers.length, 2);
+    assert.strictEqual(providers[0].name, 'a');
+    assert.strictEqual(providers[1].name, 'b');
+  });
+
+  test('clearCookieProviders removes all registered providers', () => {
+    registerCookieProvider('a', async () => undefined);
+    registerCookieProvider('b', async () => undefined);
+    assert.strictEqual(_getProviders().length, 2);
+
+    clearCookieProviders();
+    assert.strictEqual(_getProviders().length, 0);
+  });
+});