@ampless/backend 0.2.0-alpha.1 → 0.2.0-alpha.11

package/README.ja.md

@@ -0,0 +1,130 @@
+> English: [README.md](./README.md)
+> 
+
+# @ampless/backend
+
+[ampless](https://github.com/heavymoons/ampless) 向け Amplify Gen 2 バックエンドファクトリー。IAM / SQS / DynamoDB ストリームの配線、認証 / データ / ストレージの定義、およびすべてのイベント処理 Lambda を `defineAmplessBackend(...)` ひとつのファクトリーにまとめます。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+テンプレートから切り出すことで、スキャフォールダーを再実行せずに `npm update @ampless/backend` でアップデートできます。バックエンドのバグ修正やインフラ改善はパッケージ経由で届きます。ユーザー側の `amplify/` ツリーは、ファクトリーを組み合わせる 1〜5 行のシェルだけで済みます。
+
+## インストール
+
+```bash
+npm install @ampless/backend@alpha ampless@alpha
+```
+
+ピア依存: `@aws-amplify/backend`（^1）、`aws-cdk-lib`（^2）。CLI スキャフォールダーがテンプレートの `package.json` に互換バージョンをピン留めします。
+
+## 使い方
+
+### `amplify/backend.ts`
+
+```ts
+import { defineAmplessBackend } from '@ampless/backend'
+import { auth } from './auth/resource'
+import { data } from './data/resource'
+import { storage } from './storage/resource'
+import { postConfirmation } from './auth/post-confirmation/resource'
+import { eventDispatcher } from './events/dispatcher/resource'
+import { processorTrusted } from './events/processor-trusted/resource'
+import { processorUntrusted } from './events/processor-untrusted/resource'
+import { apiKeyRenewer } from './functions/api-key-renewer/resource'
+
+export default defineAmplessBackend({
+  auth, data, storage, postConfirmation,
+  eventDispatcher, processorTrusted, processorUntrusted, apiKeyRenewer,
+})
+```
+
+### `amplify/auth/resource.ts`
+
+```ts
+import { defineAuth } from '@aws-amplify/backend'
+import { amplessAuthConfig } from '@ampless/backend'
+import { postConfirmation } from './post-confirmation/resource'
+
+export const auth = defineAuth(amplessAuthConfig({ postConfirmation }))
+```
+
+> `defineAuth` は `amplify/auth/resource.ts` 自体に記述する必要があります。Amplify Gen 2 のインポートパス検証機能が `defineAuth` / `defineData` / `defineStorage` の呼び出し元を検査し、他のファイル（`node_modules/@ampless/backend/...` 配下のラッパーを含む）から呼び出された場合に `Amplify Auth must be defined in amplify/auth/resource.ts` というエラーを投げます。`amplessAuthConfig` は props オブジェクトを返すため、ampless のデフォルト設定を失わずにこのファイルで `defineAuth(...)` を呼び出せます。
+
+### `amplify/data/resource.ts`
+
+```ts
+import { a, defineData, type ClientSchema } from '@aws-amplify/backend'
+import { amplessSchemaModels, defaultAuthorizationModes } from '@ampless/backend'
+
+const schema = a.schema({
+  ...amplessSchemaModels(a),
+  // カスタムモデルをここに追加 — 組み込みモデルと同居します：
+  // MyCustomModel: a.model({ ... }).authorization((allow) => [...]),
+})
+
+export type Schema = ClientSchema<typeof schema>
+export const data = defineData({ schema, authorizationModes: defaultAuthorizationModes })
+```
+
+3 つの AppSync JS リゾルバーファイル（`list-published-posts.js`、`get-published-post.js`、`list-posts-by-tag.js`）はテンプレート内に残ります — AppSync がリゾルバーの `entry` パスを CDK synth 時に `defineData` を呼び出すファイルからの相対パスで解決するため、pnpm でシンボリックリンクされた `node_modules` パスは解決を通過できません。`amplify/data/` 以外の場所に移動する場合は、`amplessSchemaModels(a, { resolverPaths })` で新しいパスを渡してください。
+
+### `amplify/storage/resource.ts`
+
+```ts
+import { defineStorage } from '@aws-amplify/backend'
+import { amplessStorageConfig } from '@ampless/backend'
+export const storage = defineStorage(amplessStorageConfig())
+```
+
+> 認証と同じインポートパス制約があります — `defineStorage` はこのファイルから直接呼び出す必要があります。`amplessStorageConfig` は props オブジェクトを返します。
+
+### Lambda 薄型シェル
+
+`amplify/auth/`、`amplify/events/`、`amplify/functions/` 内の各ハンドラーファイルは 1〜3 行の re-export になります。Amplify の esbuild がこのパッケージへのインポートを追跡し、実際のハンドラーコードを Lambda アーティファクトにバンドルします。
+
+```ts
+// amplify/auth/post-confirmation/handler.ts
+export { handler } from '@ampless/backend/auth/post-confirmation'
+
+// amplify/events/dispatcher/handler.ts
+export { handler } from '@ampless/backend/events/dispatcher'
+
+// amplify/events/processor-trusted/handler.ts
+import config from '../../../cms.config'
+import { createProcessorTrustedHandler } from '@ampless/backend/events/processor-trusted'
+export const handler = createProcessorTrustedHandler({
+  plugins: config.plugins,
+  site: config.site,
+})
+
+// amplify/events/processor-untrusted/handler.ts
+import config from '../../../cms.config'
+import { createProcessorUntrustedHandler } from '@ampless/backend/events/processor-untrusted'
+export const handler = createProcessorUntrustedHandler({
+  plugins: config.plugins,
+  site: config.site,
+})
+
+// amplify/functions/api-key-renewer/handler.ts
+export { handler } from '@ampless/backend/functions/api-key-renewer'
+```
+
+## サブパス
+
+- `@ampless/backend` — `defineAmplessBackend`、`amplessAuthConfig`、`amplessStorageConfig`、`amplessSchemaModels`、`extendAmplessSchema`、`defaultAuthorizationModes`
+- `@ampless/backend/auth/post-confirmation` — Lambda ハンドラー
+- `@ampless/backend/events/dispatcher` — Lambda ハンドラー
+- `@ampless/backend/events/processor-trusted` — `createProcessorTrustedHandler({ plugins, site })`
+- `@ampless/backend/events/processor-untrusted` — `createProcessorUntrustedHandler({ plugins, site })`
+- `@ampless/backend/functions/api-key-renewer` — Lambda ハンドラー
+
+## テンプレートに残るもの
+
+- `amplify/data/*.js` — AppSync JS リゾルバー（ファイルパス制約のため）。
+- すべての `resource.ts` と `handler.ts` — 薄型シェルですが、Amplify の CDK synth がユーザー側で解決する `entry: './handler.ts'` パスを保持しています。
+- `cms.config.ts` と `themes-registry.ts` — ユーザーが所有するカスタマイズサーフェス。
+- `templates/<theme>/` 以下のテーマコンポーネント — ユーザーが所有。
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,3 +1,6 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+
 # @ampless/backend
 
 Amplify Gen 2 backend factories for [ampless](https://github.com/heavymoons/ampless). Bundles the IAM / SQS / DynamoDB-stream wiring, the auth / data / storage definitions, and every event-processing Lambda behind one `defineAmplessBackend(...)` factory.

package/dist/auth/post-confirmation.js

@@ -1,3 +1,5 @@
+import "../chunk-BYXBJQAS.js";
+
 // src/auth/post-confirmation.ts
 import {
   CognitoIdentityProviderClient,

package/dist/auth/user-admin.d.ts

@@ -0,0 +1,49 @@
+import { Handler } from 'aws-lambda';
+
+type AdminRole = 'admin' | 'editor' | 'none';
+interface AdminUserDto {
+    userId: string;
+    email: string;
+    role: AdminRole;
+}
+interface SetArgs {
+    userId: string;
+    role: string;
+}
+/**
+ * Event shape that Amplify Gen 2 actually delivers to a Lambda data
+ * source attached via `a.handler.function()`. The CDK generated
+ * AppSync resource is a PIPELINE resolver whose Lambda-invocation
+ * function uses a VTL request mapping template that emits a flat
+ * payload:
+ *
+ *   {
+ *     "operation": "Invoke",
+ *     "payload": {
+ *       "typeName": "Query",
+ *       "fieldName": "listAdminUsers",
+ *       "arguments": { ... },
+ *       "identity": { ... },
+ *       "source": ..., "request": ..., "prev": ...
+ *     }
+ *   }
+ *
+ * Notably this is NOT the canonical `AppSyncResolverEvent` shape
+ * (which has `event.info.fieldName`). The `aws-lambda` package's
+ * `AppSyncResolverHandler` type is misleading here — typing the
+ * handler with it sends `event.info.fieldName` to `undefined` and
+ * blows up at runtime with
+ * `Cannot read properties of undefined (reading 'fieldName')`.
+ */
+interface UserAdminEvent {
+    typeName: string;
+    fieldName: string;
+    arguments: Partial<SetArgs>;
+    identity?: unknown;
+    source?: unknown;
+    request?: unknown;
+    prev?: unknown;
+}
+declare const handler: Handler<UserAdminEvent, AdminUserDto | AdminUserDto[] | null>;
+
+export { handler };

package/dist/auth/user-admin.js

@@ -0,0 +1,107 @@
+import "../chunk-BYXBJQAS.js";
+
+// src/auth/user-admin.ts
+import {
+  CognitoIdentityProviderClient,
+  ListUsersCommand,
+  AdminListGroupsForUserCommand,
+  AdminAddUserToGroupCommand,
+  AdminRemoveUserFromGroupCommand
+} from "@aws-sdk/client-cognito-identity-provider";
+var cognito = new CognitoIdentityProviderClient({});
+var ADMIN_GROUP = "ampless-admin";
+var EDITOR_GROUP = "ampless-editor";
+function requireUserPoolId() {
+  const v = process.env.AMPLESS_USER_POOL_ID;
+  if (!v) {
+    console.error("[user-admin] missing required env var AMPLESS_USER_POOL_ID");
+    throw new Error("user-admin: missing required env var AMPLESS_USER_POOL_ID");
+  }
+  return v;
+}
+function emailOf(user) {
+  const attr = user.Attributes?.find((a) => a.Name === "email");
+  return attr?.Value ?? "";
+}
+async function roleOf(userPoolId, username) {
+  const { Groups } = await cognito.send(
+    new AdminListGroupsForUserCommand({ UserPoolId: userPoolId, Username: username })
+  );
+  const names = (Groups ?? []).map((g) => g.GroupName);
+  if (names.includes(ADMIN_GROUP)) return "admin";
+  if (names.includes(EDITOR_GROUP)) return "editor";
+  return "none";
+}
+async function listAdminUsers(userPoolId) {
+  const { Users } = await cognito.send(
+    new ListUsersCommand({ UserPoolId: userPoolId, Limit: 60 })
+  );
+  const users = Users ?? [];
+  const out = [];
+  for (const u of users) {
+    if (!u.Username) continue;
+    const role = await roleOf(userPoolId, u.Username);
+    out.push({ userId: u.Username, email: emailOf(u), role });
+  }
+  return out;
+}
+async function setAdminUserRole(userPoolId, userId, role) {
+  for (const group of [ADMIN_GROUP, EDITOR_GROUP]) {
+    await cognito.send(
+      new AdminRemoveUserFromGroupCommand({
+        UserPoolId: userPoolId,
+        Username: userId,
+        GroupName: group
+      })
+    );
+  }
+  if (role !== "none") {
+    await cognito.send(
+      new AdminAddUserToGroupCommand({
+        UserPoolId: userPoolId,
+        Username: userId,
+        GroupName: role === "admin" ? ADMIN_GROUP : EDITOR_GROUP
+      })
+    );
+  }
+  const { Users } = await cognito.send(
+    new ListUsersCommand({
+      UserPoolId: userPoolId,
+      Filter: `sub = "${userId}"`,
+      Limit: 1
+    })
+  );
+  const user = Users?.[0];
+  const email = user ? emailOf(user) : "";
+  const finalRole = await roleOf(userPoolId, userId);
+  return { userId, email, role: finalRole };
+}
+var handler = async (event) => {
+  const userPoolId = requireUserPoolId();
+  const field = event.fieldName;
+  try {
+    if (field === "listAdminUsers") {
+      return await listAdminUsers(userPoolId);
+    }
+    if (field === "setAdminUserRole") {
+      const { userId, role } = event.arguments;
+      if (role !== "admin" && role !== "editor" && role !== "none") {
+        console.error(`[user-admin] invalid role: ${role}`);
+        throw new Error(`Invalid role: ${role}`);
+      }
+      if (!userId) {
+        console.error("[user-admin] missing userId argument");
+        throw new Error("Missing userId argument");
+      }
+      return await setAdminUserRole(userPoolId, userId, role);
+    }
+    console.error(`[user-admin] unsupported fieldName: ${field}`);
+    throw new Error(`Unsupported fieldName: ${field}`);
+  } catch (err) {
+    console.error(`[user-admin] ${field} failed:`, err);
+    throw err;
+  }
+};
+export {
+  handler
+};

package/dist/events/dispatcher.js

@@ -1,3 +1,5 @@
+import "../chunk-BYXBJQAS.js";
+
 // src/events/dispatcher.ts
 import { unmarshall } from "@aws-sdk/util-dynamodb";
 import {

package/dist/events/processor-trusted.d.ts

@@ -1,5 +1,5 @@
 import { SQSHandler } from 'aws-lambda';
-import { AmplessPlugin, Config } from 'ampless';
+import { Config } from 'ampless';
 
 interface CreateProcessorTrustedHandlerOpts {
     /**
@@ -7,8 +7,12 @@ interface CreateProcessorTrustedHandlerOpts {
      * trusted plugins itself so callers don't need to remember the
      * filter, and so adding `privileged` later only touches the handler
      * code in this package.
+     *
+     * Accepts the raw `Config['plugins']` shape (which permits string
+     * entries for future dynamic loading) — the runtime filter discards
+     * anything that isn't a plugin object.
      */
-    plugins?: AmplessPlugin[];
+    plugins?: Config['plugins'];
     /**
      * The `cms.config.site` block, surfaced to plugin hooks via
      * `ctx.site`. Pass through from the thin shell — handlers must

package/dist/events/processor-trusted.js

@@ -1,3 +1,5 @@
+import "../chunk-BYXBJQAS.js";
+
 // src/events/processor-trusted.ts
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

package/dist/events/processor-untrusted.d.ts

@@ -1,12 +1,16 @@
 import { SQSHandler } from 'aws-lambda';
-import { AmplessPlugin, Config } from 'ampless';
+import { Config } from 'ampless';
 
 interface CreateProcessorUntrustedHandlerOpts {
     /**
      * The full `cms.config.plugins` array. The handler filters down to
      * untrusted plugins itself.
+     *
+     * Accepts the raw `Config['plugins']` shape (which permits string
+     * entries for future dynamic loading) — the runtime filter discards
+     * anything that isn't a plugin object.
      */
-    plugins?: AmplessPlugin[];
+    plugins?: Config['plugins'];
     /**
      * The `cms.config.site` block, surfaced to plugin hooks via
      * `ctx.site` (read-only — untrusted plugins have no AWS-touching

package/dist/events/processor-untrusted.js

@@ -1,3 +1,5 @@
+import "../chunk-BYXBJQAS.js";
+
 // src/events/processor-untrusted.ts
 function createProcessorUntrustedHandler(opts) {
   const untrustedPlugins = (opts.plugins ?? []).filter(

package/dist/functions/api-key-renewer.js

@@ -1,3 +1,5 @@
+import "../chunk-BYXBJQAS.js";
+
 // src/functions/api-key-renewer.ts
 import {
   AppSyncClient,

package/dist/functions/mcp-handler.d.ts

@@ -0,0 +1,41 @@
+/**
+ * MCP HTTP endpoint Lambda. Phase 4: Bearer validation + JSON-RPC 2.0
+ * tool dispatch over AppSync IAM auth.
+ *
+ *   1. Reads KvStore directly (PK = 'mcp-tokens', SK = SHA-256 hex)
+ *      to validate `Authorization: Bearer amk_...`. Same narrow IAM
+ *      grant as Phase 3 (`dynamodb:GetItem` on the KvStore table).
+ *   2. Parses the incoming JSON-RPC envelope by hand (no MCP SDK
+ *      stdio transport in a Lambda runtime — overkill for the three
+ *      verbs we actually need).
+ *   3. Dispatches `tools/call` through the shared `@ampless/mcp-server/tools`
+ *      registry. The GraphqlClient implementation hits AppSync with
+ *      SigV4 (`AWS_IAM` auth mode), gated by `allow.resource(mcpHandler)
+ *      .to(['query', 'mutate'])` on Post / PostTag in the schema.
+ *
+ * Function URL event format: Lambda Function URLs emit API Gateway
+ * HTTP v2 events (https://docs.aws.amazon.com/lambda/latest/dg/urls-invocation.html#urls-payloads).
+ * Headers arrive lowercased.
+ *
+ * Note: `upload_media` is filtered out — the StorageClient flow needs
+ * presigned S3 PUT URLs (the Lambda doesn't accept the binary body
+ * itself), which lands in Phase 5.
+ */
+interface FunctionUrlEvent {
+    headers?: Record<string, string | undefined>;
+    body?: string;
+    isBase64Encoded?: boolean;
+    requestContext?: {
+        http?: {
+            method?: string;
+        };
+    };
+}
+interface FunctionUrlResult {
+    statusCode: number;
+    headers?: Record<string, string>;
+    body: string;
+}
+declare const handler: (event: FunctionUrlEvent) => Promise<FunctionUrlResult>;
+
+export { handler };