@ampless/backend 0.2.0-alpha.0 → 0.2.0-alpha.10

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.
@@ -38,12 +41,15 @@ export default defineAmplessBackend({
 ### `amplify/auth/resource.ts`
 
 ```ts
-import { defineAmplessAuth } from '@ampless/backend'
+import { defineAuth } from '@aws-amplify/backend'
+import { amplessAuthConfig } from '@ampless/backend'
 import { postConfirmation } from './post-confirmation/resource'
 
-export const auth = defineAmplessAuth({ postConfirmation })
+export const auth = defineAuth(amplessAuthConfig({ postConfirmation }))
 ```
 
+> `defineAuth` must live in `amplify/auth/resource.ts` itself. Amplify Gen 2's import-path verifier inspects the call site of `defineAuth` / `defineData` / `defineStorage` and throws `Amplify Auth must be defined in amplify/auth/resource.ts` if it's invoked from any other file (including a `node_modules/@ampless/backend/...` wrapper). `amplessAuthConfig` returns the props object so you can call `defineAuth(...)` here without losing the ampless defaults.
+
 ### `amplify/data/resource.ts`
 
 ```ts
@@ -65,10 +71,13 @@ The three AppSync JS resolver files (`list-published-posts.js`, `get-published-p
 ### `amplify/storage/resource.ts`
 
 ```ts
-import { defineAmplessStorage } from '@ampless/backend'
-export const storage = defineAmplessStorage()
+import { defineStorage } from '@aws-amplify/backend'
+import { amplessStorageConfig } from '@ampless/backend'
+export const storage = defineStorage(amplessStorageConfig())
 ```
 
+> Same import-path verifier constraint as auth — `defineStorage` has to be called from this file directly. `amplessStorageConfig` returns the props object.
+
 ### Lambda thin shells
 
 Every handler file in `amplify/auth/`, `amplify/events/`, and `amplify/functions/` becomes a 1–3 line re-export. Amplify's esbuild follows the import into this package and bundles the real handler code into the Lambda artifact.
@@ -102,7 +111,7 @@ export { handler } from '@ampless/backend/functions/api-key-renewer'
 
 ## Sub-paths
 
-- `@ampless/backend` — `defineAmplessBackend`, `defineAmplessAuth`, `defineAmplessStorage`, `amplessSchemaModels`, `extendAmplessSchema`, `defaultAuthorizationModes`
+- `@ampless/backend` — `defineAmplessBackend`, `amplessAuthConfig`, `amplessStorageConfig`, `amplessSchemaModels`, `extendAmplessSchema`, `defaultAuthorizationModes`
 - `@ampless/backend/auth/post-confirmation` — Lambda handler
 - `@ampless/backend/events/dispatcher` — Lambda handler
 - `@ampless/backend/events/processor-trusted` — `createProcessorTrustedHandler({ plugins, site })`

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,105 @@
+// 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/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-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/functions/mcp-handler.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP HTTP endpoint Lambda. Phase 3: Bearer token validation only.
+ *
+ * Reads the KvStore table directly (PK = 'mcp-tokens', SK = SHA-256
+ * hash of the plaintext token) instead of going through AppSync — the
+ * Lambda IAM role only needs `dynamodb:GetItem` on that one table,
+ * which is much narrower than `appsync:GraphQL` and avoids the
+ * IAM-auth-mode complexity of letting Lambdas call AppSync as
+ * privileged identity. Phase 4 will add AppSync IAM auth when tool
+ * dispatch actually needs schema-aware access.
+ *
+ * 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.
+ */
+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 };

package/dist/functions/mcp-handler.js

@@ -0,0 +1,70 @@
+// src/functions/mcp-handler.ts
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";
+import { createHash } from "crypto";
+var TOKENS_PK = "mcp-tokens";
+function requireEnv(name) {
+  const v = process.env[name];
+  if (!v) throw new Error(`[mcp-handler] missing required env var ${name}`);
+  return v;
+}
+var KV_TABLE = requireEnv("AMPLESS_KV_TABLE");
+var ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+function hashToken(plain) {
+  return createHash("sha256").update(plain).digest("hex");
+}
+function jsonResponse(statusCode, body) {
+  return {
+    statusCode,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  };
+}
+async function validateBearer(plaintext) {
+  const hash = hashToken(plaintext);
+  const res = await ddb.send(
+    new GetCommand({
+      TableName: KV_TABLE,
+      Key: { pk: TOKENS_PK, sk: hash }
+    })
+  );
+  const row = res.Item;
+  if (!row?.value) return null;
+  let meta;
+  try {
+    meta = JSON.parse(row.value);
+  } catch {
+    console.error("[mcp-handler] could not parse token row", { hash });
+    return null;
+  }
+  if (meta.revokedAt) return null;
+  if (meta.expiresAt && new Date(meta.expiresAt).getTime() <= Date.now()) return null;
+  return meta;
+}
+var handler = async (event) => {
+  if (event.requestContext?.http?.method === "OPTIONS") {
+    return { statusCode: 204, body: "" };
+  }
+  const authHeader = event.headers?.authorization ?? event.headers?.Authorization;
+  if (!authHeader) {
+    return jsonResponse(401, { error: "missing_authorization" });
+  }
+  const match = /^Bearer\s+(amk_[A-Za-z0-9_-]+)$/.exec(authHeader);
+  if (!match) {
+    return jsonResponse(401, { error: "invalid_authorization" });
+  }
+  const plaintext = match[1];
+  const meta = await validateBearer(plaintext);
+  if (!meta) {
+    return jsonResponse(401, { error: "invalid_token" });
+  }
+  return jsonResponse(200, {
+    ok: true,
+    tokenPrefix: meta.prefix,
+    scope: meta.scope,
+    note: "Phase 3 stub. JSON-RPC tool dispatch lands in Phase 4."
+  });
+};
+export {
+  handler
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { defineData } from '@aws-amplify/backend';
+import { defineAuth, defineStorage, defineData } from '@aws-amplify/backend';
 
 type AuthResource = any;
 type DataResource = any;
@@ -13,6 +13,8 @@ interface DefineAmplessBackendOpts {
     processorTrusted: FunctionResource;
     processorUntrusted: FunctionResource;
     apiKeyRenewer: FunctionResource;
+    userAdmin: FunctionResource;
+    mcpHandler: FunctionResource;
 }
 type AmplessBackend = any;
 /**
@@ -44,7 +46,7 @@ type AmplessBackend = any;
  */
 declare function defineAmplessBackend(opts: DefineAmplessBackendOpts): AmplessBackend;
 
-interface DefineAmplessAuthOpts {
+interface AmplessAuthConfigOpts {
     /**
      * The `post-confirmation` Cognito Lambda trigger that promotes the
      * first signup to `ampless-admin`. Wire your own `defineFunction`
@@ -59,17 +61,35 @@ interface DefineAmplessAuthOpts {
     postConfirmation?: unknown;
 }
 /**
- * Provision the ampless Cognito User Pool / Identity Pool with the
- * three role groups and the optional post-confirmation trigger.
+ * Build the ampless Cognito configuration (User Pool + Identity Pool
+ * with the three role groups and the optional post-confirmation
+ * trigger) as a plain options object suitable for `defineAuth(...)`.
+ *
+ * Returning a config object — rather than calling `defineAuth`
+ * internally — keeps the actual `defineAuth` call inside the user's
+ * `amplify/auth/resource.ts`. Amplify Gen 2's import-path verifier
+ * (`@aws-amplify/backend-auth/lib/factory.js`) inspects the second
+ * stack frame and requires the call site to live at
+ * `amplify/auth/resource.ts`; routing through this package fails
+ * that check.
  *
  * Public reads use AppSync's API key (not the guest Identity Pool
  * role) because `a.handler.custom` doesn't accept `allow.guest()`
  * in Amplify Gen 2 — see `data/resource.ts` and the RUNBOOK.
+ *
+ * Usage:
+ *
+ *     // amplify/auth/resource.ts
+ *     import { defineAuth } from '@aws-amplify/backend'
+ *     import { amplessAuthConfig } from '@ampless/backend'
+ *     import { postConfirmation } from './post-confirmation/resource.js'
+ *     export const auth = defineAuth(amplessAuthConfig({ postConfirmation }))
  */
-declare function defineAmplessAuth(opts?: DefineAmplessAuthOpts): any;
+declare function amplessAuthConfig(opts?: AmplessAuthConfigOpts): Parameters<typeof defineAuth>[0];
 
 /**
- * Provision the ampless S3 bucket with the standard access map:
+ * Build the ampless S3 bucket configuration as a plain options object
+ * suitable for `defineStorage(...)`. Access map:
  *   - `public/media/*`   — guest read, admin/editor full
  *   - `public/plugins/*` — guest read, admin full
  *
@@ -77,12 +97,22 @@ declare function defineAmplessAuth(opts?: DefineAmplessAuthOpts): any;
  * `public/site-settings/*`) are applied by `defineAmplessBackend`
  * after `defineBackend` runs.
  *
- * Return type is `unknown` because Amplify's storage construct type
- * carries internal pnpm paths that don't survive declaration emit —
- * the resulting `storage` resource flows into `defineAmplessBackend`
- * unchanged.
+ * Returning a config object — rather than calling `defineStorage`
+ * internally — keeps the actual `defineStorage` call inside the
+ * user's `amplify/storage/resource.ts`. Amplify Gen 2's import-path
+ * verifier (`@aws-amplify/backend-storage/lib/factory.js`) inspects
+ * the second stack frame and requires the call site to live at
+ * `amplify/storage/resource.ts`; routing through this package fails
+ * that check.
+ *
+ * Usage:
+ *
+ *     // amplify/storage/resource.ts
+ *     import { defineStorage } from '@aws-amplify/backend'
+ *     import { amplessStorageConfig } from '@ampless/backend'
+ *     export const storage = defineStorage(amplessStorageConfig())
  */
-declare function defineAmplessStorage(): any;
+declare function amplessStorageConfig(): Parameters<typeof defineStorage>[0];
 
 interface AmplessResolverPaths {
     listPublishedPosts: string;
@@ -108,6 +138,17 @@ interface AmplessSchemaModelsOpts {
      * they must point to actual `.js` files inside the user's project.
      */
     resolverPaths?: Partial<AmplessResolverPaths>;
+    /**
+     * Optional Amplify `defineFunction` ref backing the user-admin
+     * AppSync ops (`listAdminUsers` query, `setAdminUserRole` mutation).
+     * When supplied, the corresponding `AdminUser` customType + the two
+     * ops are added to the schema, both gated to `ampless-admin`.
+     *
+     * Typed as `unknown` because `defineFunction`'s return type carries
+     * internal pnpm paths that don't survive declaration emit — same
+     * pattern as `AmplessAuthConfigOpts.postConfirmation`.
+     */
+    userAdminFunction?: unknown;
 }
 /**
  * The Ampless model + custom query definitions, returned as a plain
@@ -125,6 +166,9 @@ interface AmplessSchemaModelsOpts {
  * extra models.
  */
 declare function amplessSchemaModels(a: any, opts?: AmplessSchemaModelsOpts): {
+    AdminUser?: any;
+    listAdminUsers?: any;
+    setAdminUserRole?: any;
     Post: any;
     Page: any;
     Media: any;
@@ -155,4 +199,4 @@ declare function extendAmplessSchema(a: any, custom?: Record<string, any>, opts?
  */
 declare const defaultAuthorizationModes: Parameters<typeof defineData>[0]['authorizationModes'];
 
-export { type AmplessBackend, type AmplessResolverPaths, type AmplessSchemaModelsOpts, DEFAULT_RESOLVER_PATHS, type DefineAmplessAuthOpts, type DefineAmplessBackendOpts, amplessSchemaModels, defaultAuthorizationModes, defineAmplessAuth, defineAmplessBackend, defineAmplessStorage, extendAmplessSchema };
+export { type AmplessAuthConfigOpts, type AmplessBackend, type AmplessResolverPaths, type AmplessSchemaModelsOpts, DEFAULT_RESOLVER_PATHS, type DefineAmplessBackendOpts, amplessAuthConfig, amplessSchemaModels, amplessStorageConfig, defaultAuthorizationModes, defineAmplessBackend, extendAmplessSchema };

package/dist/index.js

@@ -3,7 +3,7 @@ import { defineBackend } from "@aws-amplify/backend";
 import { Effect, PolicyStatement, AnyPrincipal } from "aws-cdk-lib/aws-iam";
 import { Duration, Stack } from "aws-cdk-lib";
 import { Queue } from "aws-cdk-lib/aws-sqs";
-import { StartingPosition } from "aws-cdk-lib/aws-lambda";
+import { FunctionUrlAuthType, HttpMethod, StartingPosition } from "aws-cdk-lib/aws-lambda";
 import { DynamoEventSource, SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { Rule, Schedule } from "aws-cdk-lib/aws-events";
 import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";
@@ -16,7 +16,9 @@ function defineAmplessBackend(opts) {
     eventDispatcher: opts.eventDispatcher,
     processorTrusted: opts.processorTrusted,
     processorUntrusted: opts.processorUntrusted,
-    apiKeyRenewer: opts.apiKeyRenewer
+    apiKeyRenewer: opts.apiKeyRenewer,
+    userAdmin: opts.userAdmin,
+    mcpHandler: opts.mcpHandler
   });
   const cfnBucket = backend.storage.resources.cfnResources.cfnBucket;
   cfnBucket.publicAccessBlockConfiguration = {
@@ -61,6 +63,22 @@ function defineAmplessBackend(opts) {
       resources: ["arn:aws:cognito-idp:*:*:userpool/*"]
     })
   );
+  backend.userAdmin.resources.lambda.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: [
+        "cognito-idp:ListUsers",
+        "cognito-idp:AdminListGroupsForUser",
+        "cognito-idp:AdminAddUserToGroup",
+        "cognito-idp:AdminRemoveUserFromGroup"
+      ],
+      resources: ["arn:aws:cognito-idp:*:*:userpool/*"]
+    })
+  );
+  backend.userAdmin.resources.lambda.addEnvironment(
+    "AMPLESS_USER_POOL_ID",
+    backend.auth.resources.userPool.userPoolId
+  );
   const postTable = backend.data.resources.tables["Post"];
   const cfnPostTable = backend.data.resources.cfnResources.amplifyDynamoDbTables["Post"];
   cfnPostTable.streamSpecification = { streamViewType: "NEW_AND_OLD_IMAGES" };
@@ -149,13 +167,37 @@ function defineAmplessBackend(opts) {
     schedule: Schedule.cron({ minute: "0", hour: "3", day: "1", month: "*", year: "*" }),
     targets: [new LambdaFunction(apiKeyRenewerFn)]
   });
+  const mcpHandlerFn = backend.mcpHandler.resources.lambda;
+  mcpHandlerFn.addToRolePolicy(
+    new PolicyStatement({
+      effect: Effect.ALLOW,
+      actions: ["dynamodb:GetItem"],
+      resources: [kvTable.tableArn]
+    })
+  );
+  mcpHandlerFn.addEnvironment("AMPLESS_KV_TABLE", kvTable.tableName);
+  const mcpFunctionUrl = mcpHandlerFn.addFunctionUrl({
+    authType: FunctionUrlAuthType.NONE,
+    cors: {
+      allowedOrigins: ["*"],
+      allowedMethods: [HttpMethod.POST],
+      allowedHeaders: ["*"],
+      maxAge: Duration.hours(1)
+    }
+  });
+  backend.addOutput({
+    custom: {
+      mcp: {
+        endpoint: mcpFunctionUrl.url
+      }
+    }
+  });
   return backend;
 }
 
 // src/auth/index.ts
-import { defineAuth } from "@aws-amplify/backend";
-function defineAmplessAuth(opts = {}) {
-  return defineAuth({
+function amplessAuthConfig(opts = {}) {
+  return {
     loginWith: {
       email: true
     },
@@ -164,13 +206,12 @@ function defineAmplessAuth(opts = {}) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       { postConfirmation: opts.postConfirmation }
     ) : void 0
-  });
+  };
 }
 
 // src/storage/index.ts
-import { defineStorage } from "@aws-amplify/backend";
-function defineAmplessStorage() {
-  return defineStorage({
+function amplessStorageConfig() {
+  return {
     name: "amplessMedia",
     access: (allow) => ({
       "public/media/*": [
@@ -182,7 +223,7 @@ function defineAmplessStorage() {
         allow.groups(["ampless-admin"]).to(["read", "write", "delete"])
       ]
     })
-  });
+  };
 }
 
 // src/data/index.ts
@@ -203,11 +244,19 @@ function amplessSchemaModels(a, opts = {}) {
       slug: a.string().required(),
       title: a.string().required(),
       excerpt: a.string(),
-      format: a.enum(["tiptap", "markdown", "html"]),
+      format: a.enum(["tiptap", "markdown", "html", "static"]),
       body: a.json(),
       status: a.enum(["draft", "published"]),
       publishedAt: a.datetime(),
       tags: a.string().array(),
+      // Free-form per-post metadata (JSON). Reserved well-known keys
+      // are documented on `PostMetadata` in `ampless/src/types.ts`.
+      // Currently:
+      //   no_layout: boolean — serve the post as bare HTML (no theme
+      //     chrome). The runtime's post dispatcher redirects to the
+      //     raw route handler when this is true.
+      // Other keys are passed through unchanged for plugin / app use.
+      metadata: a.json(),
       // Denormalized GSI keys — set by every write path (admin client,
       // MCP tools). Same pattern as siteIdStatus: composing the
       // partition key as a single string lets each public-read query
@@ -229,7 +278,7 @@ function amplessSchemaModels(a, opts = {}) {
       pageId: a.id().required(),
       slug: a.string().required(),
       title: a.string().required(),
-      format: a.enum(["tiptap", "markdown", "html"]),
+      format: a.enum(["tiptap", "markdown", "html", "static"]),
       body: a.json(),
       status: a.enum(["draft", "published"]),
       publishedAt: a.datetime()
@@ -310,7 +359,8 @@ function amplessSchemaModels(a, opts = {}) {
       body: a.json(),
       status: a.string(),
       publishedAt: a.datetime(),
-      tags: a.string().array()
+      tags: a.string().array(),
+      metadata: a.json()
     }),
     // Paginated wrapper for list responses.
     PublicPostConnection: a.customType({
@@ -369,7 +419,27 @@ function amplessSchemaModels(a, opts = {}) {
     ).authorization((allow) => [
       allow.publicApiKey(),
       allow.groups(["ampless-admin", "ampless-editor"])
-    ])
+    ]),
+    // User management ops, only wired when the caller supplies a
+    // Lambda function ref. Conditionally spread because
+    // `a.handler.function(undefined)` is not a valid call — projects
+    // that haven't opted into the user-admin Lambda must not see
+    // these schema entries.
+    ...opts.userAdminFunction ? {
+      AdminUser: a.customType({
+        userId: a.string().required(),
+        email: a.string().required(),
+        // 'admin' | 'editor' | 'none' — stored as string because
+        // a.enum() in customType doesn't round-trip cleanly across
+        // AppSync's typegen + the admin client cast pattern.
+        role: a.string().required()
+      }),
+      listAdminUsers: a.query().returns(a.ref("AdminUser").array()).handler(a.handler.function(opts.userAdminFunction)).authorization((allow) => [allow.groups(["ampless-admin"])]),
+      setAdminUserRole: a.mutation().arguments({
+        userId: a.string().required(),
+        role: a.string().required()
+      }).returns(a.ref("AdminUser")).handler(a.handler.function(opts.userAdminFunction)).authorization((allow) => [allow.groups(["ampless-admin"])])
+    } : {}
   };
 }
 function extendAmplessSchema(a, custom, opts) {
@@ -384,10 +454,10 @@ var defaultAuthorizationModes = {
 };
 export {
   DEFAULT_RESOLVER_PATHS,
+  amplessAuthConfig,
   amplessSchemaModels,
+  amplessStorageConfig,
   defaultAuthorizationModes,
-  defineAmplessAuth,
   defineAmplessBackend,
-  defineAmplessStorage,
   extendAmplessSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/backend",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.10",
   "description": "Amplify Gen 2 backend factories for ampless: auth, data, storage, event processors, API key renewer",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,10 @@
       "import": "./dist/auth/post-confirmation.js",
       "types": "./dist/auth/post-confirmation.d.ts"
     },
+    "./auth/user-admin": {
+      "import": "./dist/auth/user-admin.js",
+      "types": "./dist/auth/user-admin.d.ts"
+    },
     "./events/dispatcher": {
       "import": "./dist/events/dispatcher.js",
       "types": "./dist/events/dispatcher.d.ts"
@@ -28,6 +32,10 @@
     "./functions/api-key-renewer": {
       "import": "./dist/functions/api-key-renewer.js",
       "types": "./dist/functions/api-key-renewer.d.ts"
+    },
+    "./functions/mcp-handler": {
+      "import": "./dist/functions/mcp-handler.js",
+      "types": "./dist/functions/mcp-handler.d.ts"
     }
   },
   "files": [
@@ -48,11 +56,11 @@
     "@aws-sdk/client-appsync": "^3.717.0",
     "@aws-sdk/client-cognito-identity-provider": "^3.717.0",
     "@aws-sdk/client-dynamodb": "^3.717.0",
-    "@aws-sdk/client-s3": "^3.717.0",
+    "@aws-sdk/client-s3": "^3.1048.0",
     "@aws-sdk/client-sqs": "^3.717.0",
     "@aws-sdk/lib-dynamodb": "^3.717.0",
     "@aws-sdk/util-dynamodb": "^3.717.0",
-    "ampless": "0.2.0-alpha.0"
+    "ampless": "0.2.0-alpha.6"
   },
   "peerDependencies": {
     "@aws-amplify/backend": "^1",