ampless 1.0.0-alpha.18 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -283,9 +283,11 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * declaration-vs-implementation reconciliation warnings and (in later
  * phases) for `allowCapabilities` gating in `cms.config.ts`.
  *
- * Phase 1 active capabilities:
+ * Active capabilities:
  *   - `publicHead` / `publicBody`: descriptor-based head/body injection.
  *   - `metadata` / `eventHooks`: name-only declaration for existing surfaces.
+ *   - `adminSettings`: admin-managed public settings manifest.
+ *   - `writePublicAsset`: trusted hook context can write namespaced public assets.
  *
  * Reserved capabilities are accepted by the type so that plugins can
  * declare future intent, but the runtime does nothing with them yet —
@@ -293,7 +295,7 @@ type TrustLevel = 'untrusted' | 'trusted' | 'privileged';
  * capability today is harmless, but the runtime won't expose any new
  * surface for it until the matching phase ships.
  */
-type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'schema' | 'writePublicAsset' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
+type PluginCapability = 'publicHead' | 'publicBody' | 'metadata' | 'eventHooks' | 'adminSettings' | 'writePublicAsset' | 'schema' | 'contentFields' | 'adminPage' | 'serverRoute' | 'secretSettings' | 'network' | 'scheduler' | 'storageWrite' | 'privilegedSystem';
 /**
  * Loading strategy for `script` / `inlineScript` descriptors.
  *
@@ -1026,6 +1028,15 @@ declare function decodeAwsJson(value: unknown): unknown;
  */
 declare function formatPublicAssetUrl(bucket: string, region: string, key: string): string;
 
+/**
+ * Validate the user-supplied key for ctx.writePublicAsset.
+ *
+ * The trusted Lambda still has a processor-wide S3 grant, so path safety is
+ * enforced at the runtime context boundary before the key is joined under the
+ * plugin namespace.
+ */
+declare function validatePublicAssetKey(key: string): string | null;
+
 declare const PLUGIN_KEY_PATTERN: RegExp;
 declare function isValidPluginKey(key: string): boolean;
 /**
@@ -1178,4 +1189,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPublicRenderContext, type PluginRuntimeContext, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPublicRenderContext, type PluginRuntimeContext, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -215,6 +215,25 @@ function definePlugin(p) {
   return p;
 }
 
+// src/plugin-asset-key.ts
+function validatePublicAssetKey(key) {
+  if (key.length === 0) return "key must not be empty";
+  if (key.length > 256) return "key must be 256 characters or less";
+  if (key.startsWith("/")) return 'key must be relative and must not start with "/"';
+  if (key.includes("\\")) return "key must not contain backslashes";
+  if (/[\u0000-\u001f\u007f]/.test(key)) {
+    return "key must not contain control characters";
+  }
+  if (!/^[A-Za-z0-9._/-]+$/.test(key)) {
+    return 'key may only contain ASCII letters, digits, ".", "_", "-", and "/" (path separator)';
+  }
+  const segments = key.split("/");
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return 'key must not contain "." or ".." path segments';
+  }
+  return null;
+}
+
 // src/plugin-settings.ts
 var PLUGIN_KEY_PATTERN = /^[a-zA-Z0-9_-]+$/;
 function isValidPluginKey(key) {
@@ -721,5 +740,6 @@ export {
   validateBundle,
   validateBundlePath,
   validatePluginSettingValue,
+  validatePublicAssetKey,
   validateThemeValue
 };

package/docs/plugin-author-guide.ja.md

@@ -139,7 +139,7 @@ analyticsGa4Plugin({ instanceId: 'product' })
 | 階層 | IAM | 用途 |
 |---|---|---|
 | `untrusted` | なし (SQS consume のみ) | head/body descriptor、webhook 配送、コンテンツ変換 |
-| `trusted` | 投稿読み出し、`public/plugins/<name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
+| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
 | `privileged` | 予約 | 将来: SES、secret、private S3 |
 
 決め方の目安:
@@ -273,6 +273,26 @@ hooks: {
 }
 ```
 
+### `writePublicAsset`
+
+公開生成ファイルを書き出す trusted plugin は capability を宣言してください:
+
+```ts
+capabilities: ['eventHooks', 'writePublicAsset']
+```
+
+同じ plugin が `metadata()` または `siteMetadata()` も実装する場合は、`metadata` も宣言します。この capability 名は両方の metadata 関数をまとめて表し、別個の `siteMetadata` capability はありません。
+
+trusted processor は次の場所に書き込みます:
+
+```txt
+public/plugins/<instanceId ?? name>/<key>
+```
+
+`key` は allowlist `[A-Za-z0-9._/-]+` に一致する必要があります。それ以外（スペース、URL 予約文字 `#` `?` `&` `=` `+`、非 ASCII 文字 (`日本語.xml` 等)、空文字、絶対パス（`/` 始まり）、`.` / `..` path segment、backslash、制御文字、256 文字超）は S3 呼び出し前に拒否されます。`indexes/posts.json` のような nested path や `feed.v2.xml` のような複数 dot は許可されます。allowlist を厳しく絞っているのは、返却 URL と実 S3 key を byte 等しい文字列に保つため — URL 予約文字は S3 では生バイトとして通るが、URL を consumer が parse すると別 object を指す状態になる。user 由来の文字を key に入れたい場合は事前に sanitize (hash、slugify 等) してから `ctx.writePublicAsset()` を呼んでください。戻り値は書き込まれた object の public URL です。
+
+移行期間中、`capabilities` フィールドが無い plugin はそのまま動きます。`capabilities` を宣言しているのに `writePublicAsset` を省いた plugin は、実際に `ctx.writePublicAsset()` を呼んだ時に 1 回だけ warn します。
+
 ### ベストプラクティス
 
 - **冪等にする**。SQS は at-least-once 配送 — 同じイベントが 2 回 fire する可能性があります。同じ入力で同じ出力 (決定論的なフィード等) を生成するようにしてください
@@ -467,6 +487,8 @@ it('admin が空文字保存した場合は空配列', () => {
 参考実装:
 
 - [`packages/plugin-analytics-ga4`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-analytics-ga4) — descriptor ベース、Phase 2 settings
+- [`packages/plugin-gtm`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-gtm) — `publicHead`（ローダーインラインスクリプト）+ `publicBodyEnd`（`<noscript>` iframe フォールバック）を両方使用、コンテナ ID は admin 編集可能
+- [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — `data-*` attrs 付きの単一 `<script>` descriptor、`required` な URL field（self-hosted Plausible 上書き対応）
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted、非同期 hooks + `writePublicAsset`
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`
 - [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook + 外向き HTTP

package/docs/plugin-author-guide.md

@@ -168,7 +168,7 @@ touch IAM):
 | Tier | IAM | Used by |
 |---|---|---|
 | `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
-| `trusted` | read posts, write `public/plugins/<name>/...` | RSS feed, sitemap, computed JSON indexes |
+| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | RSS feed, sitemap, computed JSON indexes |
 | `privileged` | reserved | future: SES, secrets, private S3 |
 
 Rule of thumb:
@@ -332,6 +332,44 @@ hooks: {
 }
 ```
 
+### `writePublicAsset`
+
+Trusted plugins that write public generated files should declare the
+capability:
+
+```ts
+capabilities: ['eventHooks', 'writePublicAsset']
+```
+
+If the same plugin implements `metadata()` or `siteMetadata()`, also
+declare `metadata`. That capability name covers both metadata
+functions; there is no separate `siteMetadata` capability.
+
+The trusted processor writes under:
+
+```txt
+public/plugins/<instanceId ?? name>/<key>
+```
+
+`key` must match the allowlist `[A-Za-z0-9._/-]+`. Anything outside
+that — spaces, URL-reserved characters (`#`, `?`, `&`, `=`, `+`),
+non-ASCII (`日本語.xml`), empty strings, absolute paths (leading `/`),
+`.` / `..` path segments, backslashes, control characters, or keys
+over 256 characters — is rejected before S3 is called. Nested paths
+such as `indexes/posts.json` and dotted extensions such as
+`feed.v2.xml` are allowed. The allowlist is deliberately tight so
+the returned public URL and the underlying S3 key are byte-identical
+strings; URL-reserved characters would survive S3 but reshape the URL
+when a consumer parses it. If you need to include user-supplied
+characters in a key, sanitize first (e.g. hash, slugify) before
+calling `ctx.writePublicAsset()`. The return value is the public URL
+for the written object.
+
+During the migration period, plugins with no `capabilities` field
+keep working. Plugins that do declare `capabilities` but omit
+`writePublicAsset` warn once when they actually call
+`ctx.writePublicAsset()`.
+
 ### Best practices
 
 - **Be idempotent.** SQS delivery is at-least-once: the same event
@@ -575,6 +613,8 @@ a normal npm package:
 Worked examples to crib from:
 
 - [`packages/plugin-analytics-ga4`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-analytics-ga4) — descriptor-based, Phase 2 settings.
+- [`packages/plugin-gtm`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-gtm) — uses both `publicHead` (loader inline script) and `publicBodyEnd` (`<noscript>` iframe fallback) with the container ID admin-edited.
+- [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — single `<script>` descriptor with `data-*` attrs and a required URL field (self-hosted Plausible override).
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted, async event hooks + `writePublicAsset`.
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`.
 - [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook with outbound HTTP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.18",
+  "version": "1.0.0-alpha.20",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",