@specific.dev/spectest 0.95.0 → 0.97.0

package/README.md

@@ -17,11 +17,14 @@ and run `spectest docs /installation` for project setup and authentication.
 
 ## Google Cloud Pub/Sub
 
+Google Cloud components are available from `@specific.dev/spectest/components/gcp`.
+The existing Pub/Sub exports from `/components` remain supported.
+
 `pubsub()` runs Google's local emulator and creates topics/subscriptions before
 dependent services start:
 
 ```ts
-import { pubsub } from "@specific.dev/spectest/components";
+import { pubsub } from "@specific.dev/spectest/components/gcp";
 
 const services = {
   messages: pubsub({
@@ -40,6 +43,12 @@ the emulator's live state. See `examples/google-pubsub` and
 `spectest docs /components/pubsub` for test credential setup and options.
 Set `tls: false` to use explicit plaintext emulator mode instead.
 
+Push subscriptions support HTTPS, `pushConfig.oidcToken`, `deadLetterPolicy`,
+and `retryPolicy`. Add the `google()` component for locally signed service-account
+ID tokens verified through Google’s normal certificate endpoints. Declare
+authenticated subscriptions in `subscriptions` or through the component’s
+`createSubscription` helper; raw emulator API calls do not add authentication.
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/components/aws.js

@@ -94,13 +94,23 @@ const AWS_REGIONS = [
 const AWS_CN_REGIONS = ["cn-north-1", "cn-northwest-1"];
 /** Every hostname pattern the emulator answers to: the two partitions' global
  *  endpoints (`sts.amazonaws.com`, `iam.amazonaws.com`) plus one per region
- *  for the regional ones (`states.us-east-1.amazonaws.com`). */
+ *  for the regional ones (`states.us-east-1.amazonaws.com`). ECR adds
+ *  labels for its API and account registries, each needing its own SAN. */
 const AWS_HOST_PATTERNS = [
     "*.amazonaws.com",
-    ...AWS_REGIONS.map((r) => `*.${r}.amazonaws.com`),
+    ...AWS_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com")),
     "*.amazonaws.com.cn",
-    ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
+    ...AWS_CN_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com.cn")),
 ];
+function regionalHostPatterns(region, suffix) {
+    return [
+        `*.${region}.${suffix}`,
+        `*.ecr.${region}.${suffix}`,
+        `*.dkr.ecr.${region}.${suffix}`,
+        `*.ecr-fips.${region}.${suffix}`,
+        `*.dkr.ecr-fips.${region}.${suffix}`,
+    ];
+}
 /** The VM's own docker socket, bind-mounted so the emulator can start the
  *  official AWS runtime containers. This is the VM's dockerd, inside the
  *  hermetic environment — the same daemon that runs the services. */

package/dist/components/emulate/entry.mjs

@@ -30,7 +30,7 @@
 // the whole OAuth exchange is readable on the case page with no helper API.
 
 import { createServer } from "@emulators/core";
-import { SignJWT, decodeJwt, exportJWK } from "jose";
+import { SignJWT, decodeJwt, exportJWK, exportPKCS8 } from "jose";
 
 const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
 const PORT = Number(CONFIG.port ?? 4000);
@@ -60,6 +60,37 @@ const JWKS = {
   keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
 };
 
+// Google's Node/Python clients fetch PEM certificates from /oauth2/v1/certs,
+// while browser clients use the JWK endpoint. Both must identify the same key.
+let GOOGLE_CERT;
+if ((CONFIG.providers ?? []).some(provider => provider.name === "google")) {
+  const child = Bun.spawn(["openssl", "req", "-new", "-x509", "-key", "/dev/stdin", "-days", "3650", "-subj", "/CN=spectest-google-token-signing"], {
+    stdin: new Blob([await exportPKCS8(KEY_PAIR.privateKey)]), stdout: "pipe", stderr: "pipe",
+  });
+  const [cert, error, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`google(): signing certificate setup failed: ${error}`);
+  GOOGLE_CERT = cert;
+}
+
+async function googleIdToken(req, path) {
+  const match = /^\/v1\/projects\/-\/serviceAccounts\/([^/]+):generateIdToken$/.exec(path);
+  if (!match || req.method !== "POST") return json({ error: "Unsupported IAM operation" }, 404);
+  let options, email;
+  try {
+    options = await req.json();
+    email = decodeURIComponent(match[1]);
+  } catch { return json({ error: "Invalid token request" }, 400); }
+  if (!options || !/^[^@\s]+@[^@\s]+$/.test(email) || typeof options.audience !== "string" || !options.audience) return json({ error: "serviceAccountEmail and audience are required" }, 400);
+  // Stable service-account subject; isolated test identities require no cloud credentials.
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(email)));
+  const subject = BigInt('0x' + Buffer.from(digest.slice(0, 8)).toString('hex')).toString();
+  const token = await new SignJWT(options.includeEmail ? { email, email_verified: true } : {})
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .setIssuer("https://accounts.google.com").setSubject(subject).setAudience(options.audience)
+    .setIssuedAt().setExpirationTime("1h").sign(KEY_PAIR.privateKey);
+  return json({ token }, 200);
+}
+
 // ──────────────────────────────────────────────────────────────────────────
 // Providers
 // ──────────────────────────────────────────────────────────────────────────
@@ -205,7 +236,11 @@ Bun.serve({
     }
 
     let res;
-    if (provider.oidc && provider.jwksPath?.test(path)) {
+    if (provider.name === "google" && host === "iamcredentials.googleapis.com") {
+      res = await googleIdToken(req, path);
+    } else if (provider.name === "google" && path === "/oauth2/v1/certs") {
+      res = json({ [KID]: GOOGLE_CERT }, 200);
+    } else if (provider.oidc && provider.jwksPath?.test(path)) {
       // Our key, never the emulator's — we re-sign every id_token.
       res = json(JWKS, 200);
     } else {

package/dist/components/emulate/service.js

@@ -80,6 +80,7 @@ const ENTRY_SCRIPT = (() => {
 const DOCKERFILE = `
 FROM ${IMAGE_BASE}
 WORKDIR /srv
+RUN apk add --no-cache openssl
 RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
  && bun add \\
       @emulators/core@${EMULATE_VERSION} \\

package/dist/components/gcp.d.ts

@@ -0,0 +1,2 @@
+/** Google Cloud components for local Spectest environments. */
+export { pubsub, pubsubClient, type PubSubOptions, type PubSubOidcToken, type PubSubPushConfig, type PubSubDeadLetterPolicy, type PubSubRetryPolicy, type PubSubClient, type PubSubHelpers, type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage, } from "./pubsub.js";

package/dist/components/gcp.js

@@ -0,0 +1,2 @@
+/** Google Cloud components for local Spectest environments. */
+export { pubsub, pubsubClient, } from "./pubsub.js";

package/dist/components/google.js

@@ -1,7 +1,8 @@
 // `google()` — Google, emulated inside the environment, answering at its
 // real endpoints.
 //
-// Today that is Sign in with Google: OpenID Connect discovery, the account
+// Supports service-account ID tokens (IAM generateIdToken) and Sign in
+// with Google: OpenID Connect discovery, the account
 // picker, PKCE, the token exchange, refresh, and userinfo. The component is
 // named for the provider rather than for the feature, because the backing
 // emulator also carries Gmail, Calendar and Drive — claiming
@@ -16,6 +17,7 @@ function spec(users, opts) {
         baseUrl: "https://accounts.google.com",
         hosts: [
             "accounts.google.com",
+            "iamcredentials.googleapis.com",
             "oauth2.googleapis.com",
             "www.googleapis.com",
             "openidconnect.googleapis.com",

package/dist/components/index.d.ts

@@ -1,4 +1,4 @@
-export { pubsub, pubsubClient, type PubSubOptions, type PubSubClient, type PubSubHelpers, type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage } from "./pubsub.js";
+export { pubsub, pubsubClient, type PubSubOptions, type PubSubOidcToken, type PubSubPushConfig, type PubSubDeadLetterPolicy, type PubSubRetryPolicy, type PubSubClient, type PubSubHelpers, type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage } from "./pubsub.js";
 export { temporal, temporalClient, type TemporalOptions, type TemporalClient, type TemporalNamespace, type TemporalWorkerOptions, type TemporalPoller, type TemporalSearchAttributeType, type TemporalTaskType } from "./temporal.js";
 export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgres.js";
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";

package/dist/components/pubsub-push.py

@@ -0,0 +1,83 @@
+"""Authenticated push adapter; the emulator still owns scheduling and retries.
+
+Runs only on loopback in the emulator container. Tokens come from the local
+Google IAM fake, so recipients verify them with the same Google JWKS as usual.
+Never follows redirects or acknowledges a failed token request/delivery.
+"""
+import base64
+import json
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def opener():
+    context = ssl.create_default_context(cafile=os.environ.get("SSL_CERT_FILE"))
+    return urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context))
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        phase = "configuration"
+        try:
+            if not self.path.startswith('/push/'):
+                self.send_error(404)
+                return
+            encoded = self.path[len('/push/'):]
+            config = json.loads(base64.urlsafe_b64decode(encoded + '=' * (-len(encoded) % 4)))
+            endpoint = config['endpoint']
+            if urllib.parse.urlsplit(endpoint).scheme not in ('http', 'https'):
+                raise ValueError('Invalid push endpoint')
+            size = int(self.headers.get('Content-Length', '0'))
+            if not 0 <= size <= 16 * 1024 * 1024:
+                self.send_error(413)
+                return
+            body = self.rfile.read(size)
+            account = urllib.parse.quote(config['serviceAccountEmail'], safe='')
+            token_url = 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/' + account + ':generateIdToken'
+            token_body = json.dumps({'audience': config.get('audience') or endpoint, 'includeEmail': True}).encode()
+            http = opener()
+            phase = "token issuance"
+            with http.open(urllib.request.Request(token_url, data=token_body, headers={'Content-Type': 'application/json'}), timeout=10) as response:
+                token = json.load(response)['token']
+            if not isinstance(token, str) or not token or '\r' in token or '\n' in token:
+                raise ValueError('Invalid ID token from Google IAM fake')
+            request = urllib.request.Request(endpoint, data=body, headers={
+                'Content-Type': self.headers.get('Content-Type', 'application/json'),
+                'Authorization': 'Bearer ' + token,
+            })
+            phase = "delivery"
+            with http.open(request, timeout=30) as response:
+                status = response.status
+            self.send_response(status)
+            self.end_headers()
+        except urllib.error.HTTPError as error:
+            # An unsuccessful token request or destination response must retry.
+            print(f"pubsub push {phase} returned HTTP {error.code}", flush=True)
+            self.send_response(error.code if error.code >= 300 else 502)
+            self.end_headers()
+            error.close()
+        except Exception as error:
+            # Do not log tokens, request bodies, or the encoded config URL.
+            print('pubsub push adapter failed: ' + type(error).__name__, flush=True)
+            self.send_response(502)
+            self.end_headers()
+
+    def log_message(self, format, *args):
+        pass
+
+
+if __name__ == '__main__':
+    server = ThreadingHTTPServer(('127.0.0.1', int(sys.argv[1])), Handler)
+    server.daemon_threads = True
+    print('pubsub authenticated push adapter ready', flush=True)
+    server.serve_forever()

package/dist/components/pubsub.d.ts

@@ -1,10 +1,33 @@
 import type { ServiceSetupContext, ServicesMap } from "../index.js";
+export interface PubSubOidcToken {
+    serviceAccountEmail: string;
+    /** Defaults to the original push endpoint URL. */
+    audience?: string;
+}
+export interface PubSubPushConfig {
+    pushEndpoint: string;
+    oidcToken?: PubSubOidcToken;
+    attributes?: Record<string, string>;
+}
+export interface PubSubDeadLetterPolicy {
+    /** Fully qualified projects/{project}/topics/{topic} name. Create this topic separately. */
+    deadLetterTopic: string;
+    maxDeliveryAttempts?: number;
+}
+export interface PubSubRetryPolicy {
+    /** Google duration strings, for example "1s" and "60s". */
+    minimumBackoff?: string;
+    maximumBackoff?: string;
+}
 export interface PubSubSubscriptionOptions {
     /** Topic ID in this component's project. */
     topic: string;
     ackDeadlineSeconds?: number;
-    /** HTTP is supported by the emulator, including other service names. */
+    /** Shorthand for pushConfig.pushEndpoint. HTTP and HTTPS are supported. */
     pushEndpoint?: string;
+    pushConfig?: PubSubPushConfig;
+    deadLetterPolicy?: PubSubDeadLetterPolicy;
+    retryPolicy?: PubSubRetryPolicy;
 }
 export interface PubSubOptions {
     /** Local project ID; no Google Cloud account is needed. Default "spectest". */

package/dist/components/pubsub.js

@@ -1,6 +1,8 @@
+import { readFileSync } from "node:fs";
 import { serviceGroup, certificate } from "../index.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { readRaw } from "../inspect.js";
+const PUSH_ADAPTER = readFileSync(new URL("./pubsub-push.py", import.meta.url), "utf8");
 function resourceId(id) {
     if (!/^[A-Za-z][A-Za-z0-9._~+%-]{2,254}$/.test(id) || id.startsWith("goog")) {
         throw new Error(`pubsub(): invalid topic or subscription ID ${JSON.stringify(id)}; use a 3–255 character ID starting with a letter, not "goog"`);
@@ -17,8 +19,15 @@ function subscriptionOptions(options) {
     const seconds = options.ackDeadlineSeconds ?? 10;
     if (!Number.isInteger(seconds) || seconds < 10 || seconds > 600)
         throw new Error("pubsub(): ackDeadlineSeconds must be an integer between 10 and 600");
-    if (options.pushEndpoint && !/^https?:$/.test(new URL(options.pushEndpoint).protocol))
-        throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
+    if (options.pushEndpoint && options.pushConfig && options.pushEndpoint !== options.pushConfig.pushEndpoint)
+        throw new Error("pubsub(): pushEndpoint and pushConfig.pushEndpoint disagree");
+    const push = options.pushConfig ?? (options.pushEndpoint ? { pushEndpoint: options.pushEndpoint } : undefined);
+    if (push) {
+        if (!push.pushEndpoint || !/^https?:$/.test(new URL(push.pushEndpoint).protocol))
+            throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
+        if (push.oidcToken && (!/^[^@\s]+@[^@\s]+$/.test(push.oidcToken.serviceAccountEmail) || (push.oidcToken.audience !== undefined && !push.oidcToken.audience)))
+            throw new Error("pubsub(): oidcToken requires a serviceAccountEmail and nonempty audience");
+    }
     return seconds;
 }
 /** Stateless emulator REST client. No credentials or gRPC channel to preserve across forks.
@@ -53,7 +62,9 @@ export function pubsubClient(endpoint, projectId = "spectest", fetcher = rawFetc
             const ackDeadlineSeconds = subscriptionOptions(options);
             return request(path("subscriptions", id), "PUT", {
                 topic: resource("topics", options.topic), ackDeadlineSeconds,
-                ...(options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+                ...(options.pushConfig ? { pushConfig: options.pushConfig } : options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+                ...(options.deadLetterPolicy ? { deadLetterPolicy: options.deadLetterPolicy } : {}),
+                ...(options.retryPolicy ? { retryPolicy: options.retryPolicy } : {}),
             });
         },
         async publish(topic, data, attributes) {
@@ -77,6 +88,22 @@ export function pubsubClient(endpoint, projectId = "spectest", fetcher = rawFetc
         },
     };
 }
+// The official emulator ignores OIDC. Keep its push/retry/dead-letter engine,
+// but route authenticated deliveries through a local adapter in its container.
+function authenticatedPush(options, pushPort) {
+    subscriptionOptions(options);
+    const push = options.pushConfig;
+    if (!push?.oidcToken)
+        return options;
+    const config = Buffer.from(JSON.stringify({ endpoint: push.pushEndpoint, ...push.oidcToken })).toString("base64url");
+    return {
+        ...options, pushEndpoint: undefined,
+        pushConfig: { ...push, pushEndpoint: `http://127.0.0.1:${pushPort}/push/${config}` },
+    };
+}
+function withPushAuth(client, pushPort) {
+    return { ...client, createSubscription: (id, options) => client.createSubscription(id, authenticatedPush(options, pushPort)) };
+}
 /** Google Cloud's real local Pub/Sub emulator, ready for Google client libraries.
  * Mount directly in services: { pubsub: pubsub({ topics: ["orders"] }) }.
  * Applications use their default pubsub.googleapis.com:443 endpoint with
@@ -86,6 +113,7 @@ export function pubsubClient(endpoint, projectId = "spectest", fetcher = rawFetc
 export function pubsub(opts = {}) {
     const projectId = projectName(opts.projectId ?? "spectest");
     const port = opts.port ?? 8085;
+    const pushPort = port === 8086 ? 8087 : 8086;
     const hostname = opts.tls === false ? undefined : opts.tls?.hostname ?? "pubsub.googleapis.com";
     if (hostname !== undefined) {
         certificate([hostname]);
@@ -107,12 +135,20 @@ export function pubsub(opts = {}) {
         services: () => {
             const emulator = {
                 image: { type: "registry", reference: opts.image ?? "gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-emulators" },
-                args: ["gcloud", "beta", "emulators", "pubsub", "start", `--project=${projectId}`, `--host-port=0.0.0.0:${port}`, "--quiet"],
+                args: ["sh", "-ec", `
+java_home=$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")
+cp "$java_home/lib/security/cacerts" /tmp/spectest-pubsub-cacerts
+keytool -importcert -noprompt -alias spectest-environment -keystore /tmp/spectest-pubsub-cacerts -storepass changeit -file "$NODE_EXTRA_CA_CERTS"
+export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/tmp/spectest-pubsub-cacerts -Djavax.net.ssl.trustStorePassword=changeit \${JAVA_TOOL_OPTIONS:-}"
+python3 /opt/spectest-pubsub-push.py ${pushPort} &
+exec gcloud beta emulators pubsub start --project=${projectId} --host-port=0.0.0.0:${port} --quiet
+`],
+                files: [{ path: "/opt/spectest-pubsub-push.py", content: PUSH_ADAPTER }],
                 ports: [port],
                 ...(hostname ? { tls: [{ hostname, port, http2: true }] } : {}),
                 readyCheck: { type: "http", port, path: `/v1/projects/${projectId}/topics`, timeoutSecs: 60 },
                 setup: async ({ name }) => {
-                    const client = pubsubClient(`http://${name}:${port}`, projectId);
+                    const client = withPushAuth(pubsubClient(`http://${name}:${port}`, projectId), pushPort);
                     for (const topic of topics)
                         await client.createTopic(topic);
                     for (const [id, options] of subscriptions)
@@ -122,7 +158,7 @@ export function pubsub(opts = {}) {
             return { emulator };
         },
         helpers: (ctx) => ({
-            ...pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId, async (input, init) => readRaw(await ctx.fetch(String(input), init))),
+            ...withPushAuth(pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId, async (input, init) => readRaw(await ctx.fetch(String(input), init))), pushPort),
             emulatorHost: `${ctx.name}:${port}`,
         }),
         setup: async (ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.95.0",
+  "version": "0.97.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,11 @@
       "bun": "./src/components/index.ts",
       "default": "./dist/components/index.js"
     },
+    "./components/gcp": {
+      "types": "./dist/components/gcp.d.ts",
+      "bun": "./src/components/gcp.ts",
+      "default": "./dist/components/gcp.js"
+    },
     "./coverage": {
       "types": "./dist/coverage.d.ts",
       "bun": "./src/coverage.ts",

package/src/components/aws.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defineEnvironment } from "../index.js";
+import { lowerIngress } from "../ingress.js";
+import { generateHostCert } from "../harness/certificate.js";
+import { aws } from "./aws.js";
+
+test("AWS certificate verifies nested ECR endpoints in every partition", async () => {
+  const env = defineEnvironment({ name: "test", services: { cloud: aws() } });
+  const ingress = lowerIngress(env.project([]));
+  expect(ingress.certificates).toHaveLength(1);
+  const names = ingress.certificates[0].hostnames;
+  const dir = await mkdtemp(join(tmpdir(), "spectest-aws-tls-"));
+  const ca = join(dir, "ca.crt");
+  const key = join(dir, "ca.key");
+  try {
+    const root = Bun.spawnSync(["openssl", "req", "-x509", "-newkey", "rsa:2048",
+      "-nodes", "-days", "1", "-subj", "/CN=test-ca", "-keyout", key, "-out", ca]);
+    expect(root.exitCode, root.stderr.toString()).toBe(0);
+    const { cert } = await generateHostCert("aws", names, ca, key);
+    const leaf = new X509Certificate(cert);
+    for (const host of [
+      "api.ecr.eu-central-1.amazonaws.com",
+      "123456789012.dkr.ecr.eu-central-1.amazonaws.com",
+      "api.ecr.us-gov-west-1.amazonaws.com",
+      "api.ecr-fips.us-gov-west-1.amazonaws.com",
+      "123456789012.dkr.ecr-fips.us-gov-west-1.amazonaws.com",
+      "api.ecr.cn-north-1.amazonaws.com.cn",
+      "123456789012.dkr.ecr.cn-northwest-1.amazonaws.com.cn",
+      "states.us-east-1.amazonaws.com",
+      "sts.amazonaws.com",
+    ]) {
+      const pattern = leaf.checkHost(host);
+      expect(pattern, host).toBeDefined();
+      expect(ingress.proxies).toContainEqual({ hostname: pattern, service: "cloud", port: 4566 });
+    }
+    expect(leaf.checkHost("api.ecr.eu-central-1.amazonaws.com.attacker.test")).toBeUndefined();
+    const file = join(dir, "leaf.crt");
+    await writeFile(file, cert);
+    const verified = Bun.spawnSync(["openssl", "verify", "-CAfile", ca,
+      "-verify_hostname", "api.ecr.eu-central-1.amazonaws.com", file]);
+    expect(verified.exitCode, verified.stderr.toString()).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);

package/src/components/aws.ts

@@ -101,14 +101,25 @@ const AWS_CN_REGIONS = ["cn-north-1", "cn-northwest-1"];
 
 /** Every hostname pattern the emulator answers to: the two partitions' global
  *  endpoints (`sts.amazonaws.com`, `iam.amazonaws.com`) plus one per region
- *  for the regional ones (`states.us-east-1.amazonaws.com`). */
+ *  for the regional ones (`states.us-east-1.amazonaws.com`). ECR adds
+ *  labels for its API and account registries, each needing its own SAN. */
 const AWS_HOST_PATTERNS = [
   "*.amazonaws.com",
-  ...AWS_REGIONS.map((r) => `*.${r}.amazonaws.com`),
+  ...AWS_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com")),
   "*.amazonaws.com.cn",
-  ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
+  ...AWS_CN_REGIONS.flatMap((r) => regionalHostPatterns(r, "amazonaws.com.cn")),
 ];
 
+function regionalHostPatterns(region: string, suffix: string): string[] {
+  return [
+    `*.${region}.${suffix}`,
+    `*.ecr.${region}.${suffix}`,
+    `*.dkr.ecr.${region}.${suffix}`,
+    `*.ecr-fips.${region}.${suffix}`,
+    `*.dkr.ecr-fips.${region}.${suffix}`,
+  ];
+}
+
 /** The VM's own docker socket, bind-mounted so the emulator can start the
  *  official AWS runtime containers. This is the VM's dockerd, inside the
  *  hermetic environment — the same daemon that runs the services. */

package/src/components/emulate/entry.mjs

@@ -30,7 +30,7 @@
 // the whole OAuth exchange is readable on the case page with no helper API.
 
 import { createServer } from "@emulators/core";
-import { SignJWT, decodeJwt, exportJWK } from "jose";
+import { SignJWT, decodeJwt, exportJWK, exportPKCS8 } from "jose";
 
 const CONFIG = JSON.parse(process.env.SPECTEST_AUTH_CONFIG ?? "{}");
 const PORT = Number(CONFIG.port ?? 4000);
@@ -60,6 +60,37 @@ const JWKS = {
   keys: [{ ...(await exportJWK(KEY_PAIR.publicKey)), kid: KID, use: "sig", alg: "RS256" }],
 };
 
+// Google's Node/Python clients fetch PEM certificates from /oauth2/v1/certs,
+// while browser clients use the JWK endpoint. Both must identify the same key.
+let GOOGLE_CERT;
+if ((CONFIG.providers ?? []).some(provider => provider.name === "google")) {
+  const child = Bun.spawn(["openssl", "req", "-new", "-x509", "-key", "/dev/stdin", "-days", "3650", "-subj", "/CN=spectest-google-token-signing"], {
+    stdin: new Blob([await exportPKCS8(KEY_PAIR.privateKey)]), stdout: "pipe", stderr: "pipe",
+  });
+  const [cert, error, code] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+  if (code !== 0) throw new Error(`google(): signing certificate setup failed: ${error}`);
+  GOOGLE_CERT = cert;
+}
+
+async function googleIdToken(req, path) {
+  const match = /^\/v1\/projects\/-\/serviceAccounts\/([^/]+):generateIdToken$/.exec(path);
+  if (!match || req.method !== "POST") return json({ error: "Unsupported IAM operation" }, 404);
+  let options, email;
+  try {
+    options = await req.json();
+    email = decodeURIComponent(match[1]);
+  } catch { return json({ error: "Invalid token request" }, 400); }
+  if (!options || !/^[^@\s]+@[^@\s]+$/.test(email) || typeof options.audience !== "string" || !options.audience) return json({ error: "serviceAccountEmail and audience are required" }, 400);
+  // Stable service-account subject; isolated test identities require no cloud credentials.
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(email)));
+  const subject = BigInt('0x' + Buffer.from(digest.slice(0, 8)).toString('hex')).toString();
+  const token = await new SignJWT(options.includeEmail ? { email, email_verified: true } : {})
+    .setProtectedHeader({ alg: "RS256", kid: KID, typ: "JWT" })
+    .setIssuer("https://accounts.google.com").setSubject(subject).setAudience(options.audience)
+    .setIssuedAt().setExpirationTime("1h").sign(KEY_PAIR.privateKey);
+  return json({ token }, 200);
+}
+
 // ──────────────────────────────────────────────────────────────────────────
 // Providers
 // ──────────────────────────────────────────────────────────────────────────
@@ -205,7 +236,11 @@ Bun.serve({
     }
 
     let res;
-    if (provider.oidc && provider.jwksPath?.test(path)) {
+    if (provider.name === "google" && host === "iamcredentials.googleapis.com") {
+      res = await googleIdToken(req, path);
+    } else if (provider.name === "google" && path === "/oauth2/v1/certs") {
+      res = json({ [KID]: GOOGLE_CERT }, 200);
+    } else if (provider.oidc && provider.jwksPath?.test(path)) {
       // Our key, never the emulator's — we re-sign every id_token.
       res = json(JWKS, 200);
     } else {

package/src/components/emulate/service.ts

@@ -155,6 +155,7 @@ const ENTRY_SCRIPT: string = (() => {
 const DOCKERFILE = `
 FROM ${IMAGE_BASE}
 WORKDIR /srv
+RUN apk add --no-cache openssl
 RUN echo '{"name":"spectest-provider","private":true}' > package.json \\
  && bun add \\
       @emulators/core@${EMULATE_VERSION} \\

package/src/components/gcp.ts

@@ -0,0 +1,15 @@
+/** Google Cloud components for local Spectest environments. */
+export {
+  pubsub,
+  pubsubClient,
+  type PubSubOptions,
+  type PubSubOidcToken,
+  type PubSubPushConfig,
+  type PubSubDeadLetterPolicy,
+  type PubSubRetryPolicy,
+  type PubSubClient,
+  type PubSubHelpers,
+  type PubSubSubscriptionOptions,
+  type PubSubMessage,
+  type PubSubReceivedMessage,
+} from "./pubsub.js";

package/src/components/google.ts

@@ -1,7 +1,8 @@
 // `google()` — Google, emulated inside the environment, answering at its
 // real endpoints.
 //
-// Today that is Sign in with Google: OpenID Connect discovery, the account
+// Supports service-account ID tokens (IAM generateIdToken) and Sign in
+// with Google: OpenID Connect discovery, the account
 // picker, PKCE, the token exchange, refresh, and userinfo. The component is
 // named for the provider rather than for the feature, because the backing
 // emulator also carries Gmail, Calendar and Drive — claiming
@@ -27,6 +28,7 @@ function spec(users: ProviderUser[], opts: GoogleOptions): ProviderSpec {
     baseUrl: "https://accounts.google.com",
     hosts: [
       "accounts.google.com",
+      "iamcredentials.googleapis.com",
       "oauth2.googleapis.com",
       "www.googleapis.com",
       "openidconnect.googleapis.com",

package/src/components/index.ts

@@ -1,5 +1,5 @@
 // Reusable, pre-built service definitions for common dependencies.
-export { pubsub, pubsubClient, type PubSubOptions, type PubSubClient, type PubSubHelpers,
+export { pubsub, pubsubClient, type PubSubOptions, type PubSubOidcToken, type PubSubPushConfig, type PubSubDeadLetterPolicy, type PubSubRetryPolicy, type PubSubClient, type PubSubHelpers,
   type PubSubSubscriptionOptions, type PubSubMessage, type PubSubReceivedMessage } from "./pubsub.js";
 export { temporal, temporalClient, type TemporalOptions, type TemporalClient,
   type TemporalNamespace, type TemporalWorkerOptions, type TemporalPoller,

package/src/components/pubsub-push.py

@@ -0,0 +1,83 @@
+"""Authenticated push adapter; the emulator still owns scheduling and retries.
+
+Runs only on loopback in the emulator container. Tokens come from the local
+Google IAM fake, so recipients verify them with the same Google JWKS as usual.
+Never follows redirects or acknowledges a failed token request/delivery.
+"""
+import base64
+import json
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def opener():
+    context = ssl.create_default_context(cafile=os.environ.get("SSL_CERT_FILE"))
+    return urllib.request.build_opener(NoRedirect(), urllib.request.HTTPSHandler(context=context))
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        phase = "configuration"
+        try:
+            if not self.path.startswith('/push/'):
+                self.send_error(404)
+                return
+            encoded = self.path[len('/push/'):]
+            config = json.loads(base64.urlsafe_b64decode(encoded + '=' * (-len(encoded) % 4)))
+            endpoint = config['endpoint']
+            if urllib.parse.urlsplit(endpoint).scheme not in ('http', 'https'):
+                raise ValueError('Invalid push endpoint')
+            size = int(self.headers.get('Content-Length', '0'))
+            if not 0 <= size <= 16 * 1024 * 1024:
+                self.send_error(413)
+                return
+            body = self.rfile.read(size)
+            account = urllib.parse.quote(config['serviceAccountEmail'], safe='')
+            token_url = 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/' + account + ':generateIdToken'
+            token_body = json.dumps({'audience': config.get('audience') or endpoint, 'includeEmail': True}).encode()
+            http = opener()
+            phase = "token issuance"
+            with http.open(urllib.request.Request(token_url, data=token_body, headers={'Content-Type': 'application/json'}), timeout=10) as response:
+                token = json.load(response)['token']
+            if not isinstance(token, str) or not token or '\r' in token or '\n' in token:
+                raise ValueError('Invalid ID token from Google IAM fake')
+            request = urllib.request.Request(endpoint, data=body, headers={
+                'Content-Type': self.headers.get('Content-Type', 'application/json'),
+                'Authorization': 'Bearer ' + token,
+            })
+            phase = "delivery"
+            with http.open(request, timeout=30) as response:
+                status = response.status
+            self.send_response(status)
+            self.end_headers()
+        except urllib.error.HTTPError as error:
+            # An unsuccessful token request or destination response must retry.
+            print(f"pubsub push {phase} returned HTTP {error.code}", flush=True)
+            self.send_response(error.code if error.code >= 300 else 502)
+            self.end_headers()
+            error.close()
+        except Exception as error:
+            # Do not log tokens, request bodies, or the encoded config URL.
+            print('pubsub push adapter failed: ' + type(error).__name__, flush=True)
+            self.send_response(502)
+            self.end_headers()
+
+    def log_message(self, format, *args):
+        pass
+
+
+if __name__ == '__main__':
+    server = ThreadingHTTPServer(('127.0.0.1', int(sys.argv[1])), Handler)
+    server.daemon_threads = True
+    print('pubsub authenticated push adapter ready', flush=True)
+    server.serve_forever()

package/src/components/pubsub.test.ts

@@ -6,8 +6,8 @@ describe("Pub/Sub", () => {
   test("custom port and project configure both the emulator and API readiness", () => {
     const env = defineEnvironment({ name: "test", services: { messaging: pubsub({ projectId: "local-project", port: 9095 }) } });
     const service = env.config.services.messaging;
-    expect(service.args).toContain("--host-port=0.0.0.0:9095");
-    expect(service.args).toContain("--project=local-project");
+    expect(service.args?.join("\n")).toContain("--host-port=0.0.0.0:9095");
+    expect(service.args?.join("\n")).toContain("--project=local-project");
     expect(service.tls).toEqual([{ hostname: "pubsub.googleapis.com", port: 9095, http2: true }]);
     expect(Object.keys(env.config.services)).toEqual(["messaging"]);
     const direct = defineEnvironment({ name: "test", services: { messaging: pubsub({ tls: false }) } });
@@ -86,3 +86,18 @@ describe("Pub/Sub", () => {
     await expect(client.pull("worker", { timeoutMs: 10 })).rejects.toThrow();
   });
 });
+
+
+test("subscription push authentication and delivery policies are passed through", async () => {
+  let body: any;
+  const client = pubsubClient("http://emulator:8085", "spectest", async (_, init) => {
+    body = JSON.parse(init!.body as string); return Response.json({});
+  });
+  const pushConfig = { pushEndpoint: "https://worker.run.app/push", oidcToken: { serviceAccountEmail: "push@spectest.iam.gserviceaccount.com", audience: "https://worker.run.app" }, attributes: { "x-goog-version": "v1" } };
+  const deadLetterPolicy = { deadLetterTopic: "projects/spectest/topics/dead-letters", maxDeliveryAttempts: 5 };
+  const retryPolicy = { minimumBackoff: "1s", maximumBackoff: "60s" };
+  await client.createSubscription("worker", { topic: "orders", pushConfig, deadLetterPolicy, retryPolicy });
+  expect(body).toEqual({ topic: "projects/spectest/topics/orders", ackDeadlineSeconds: 10, pushConfig, deadLetterPolicy, retryPolicy });
+  expect(() => client.createSubscription("worker", { topic: "orders", pushEndpoint: "https://other.run.app", pushConfig })).toThrow("disagree");
+  expect(() => client.createSubscription("worker", { topic: "orders", pushConfig: { ...pushConfig, oidcToken: { serviceAccountEmail: "invalid" } } })).toThrow("oidcToken");
+});

package/src/components/pubsub.ts

@@ -1,14 +1,40 @@
+import { readFileSync } from "node:fs";
 import type { ServiceDefinition, ServiceHelpersContext, ServiceSetupContext, ServicesMap } from "../index.js";
 import { serviceGroup, certificate } from "../index.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { readRaw } from "../inspect.js";
 
+const PUSH_ADAPTER = readFileSync(new URL("./pubsub-push.py", import.meta.url), "utf8");
+
+export interface PubSubOidcToken {
+  serviceAccountEmail: string;
+  /** Defaults to the original push endpoint URL. */
+  audience?: string;
+}
+export interface PubSubPushConfig {
+  pushEndpoint: string;
+  oidcToken?: PubSubOidcToken;
+  attributes?: Record<string, string>;
+}
+export interface PubSubDeadLetterPolicy {
+  /** Fully qualified projects/{project}/topics/{topic} name. Create this topic separately. */
+  deadLetterTopic: string;
+  maxDeliveryAttempts?: number;
+}
+export interface PubSubRetryPolicy {
+  /** Google duration strings, for example "1s" and "60s". */
+  minimumBackoff?: string;
+  maximumBackoff?: string;
+}
 export interface PubSubSubscriptionOptions {
   /** Topic ID in this component's project. */
   topic: string;
   ackDeadlineSeconds?: number;
-  /** HTTP is supported by the emulator, including other service names. */
+  /** Shorthand for pushConfig.pushEndpoint. HTTP and HTTPS are supported. */
   pushEndpoint?: string;
+  pushConfig?: PubSubPushConfig;
+  deadLetterPolicy?: PubSubDeadLetterPolicy;
+  retryPolicy?: PubSubRetryPolicy;
 }
 
 export interface PubSubOptions {
@@ -59,7 +85,12 @@ function subscriptionOptions(options: PubSubSubscriptionOptions) {
   resourceId(options.topic);
   const seconds = options.ackDeadlineSeconds ?? 10;
   if (!Number.isInteger(seconds) || seconds < 10 || seconds > 600) throw new Error("pubsub(): ackDeadlineSeconds must be an integer between 10 and 600");
-  if (options.pushEndpoint && !/^https?:$/.test(new URL(options.pushEndpoint).protocol)) throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
+  if (options.pushEndpoint && options.pushConfig && options.pushEndpoint !== options.pushConfig.pushEndpoint) throw new Error("pubsub(): pushEndpoint and pushConfig.pushEndpoint disagree");
+  const push = options.pushConfig ?? (options.pushEndpoint ? { pushEndpoint: options.pushEndpoint } : undefined);
+  if (push) {
+    if (!push.pushEndpoint || !/^https?:$/.test(new URL(push.pushEndpoint).protocol)) throw new Error("pubsub(): pushEndpoint must use HTTP or HTTPS");
+    if (push.oidcToken && (!/^[^@\s]+@[^@\s]+$/.test(push.oidcToken.serviceAccountEmail) || (push.oidcToken.audience !== undefined && !push.oidcToken.audience))) throw new Error("pubsub(): oidcToken requires a serviceAccountEmail and nonempty audience");
+  }
   return seconds;
 }
 
@@ -97,7 +128,9 @@ export function pubsubClient(
       const ackDeadlineSeconds = subscriptionOptions(options);
       return request<{ name: string; topic: string; ackDeadlineSeconds: number }>(path("subscriptions", id), "PUT", {
         topic: resource("topics", options.topic), ackDeadlineSeconds,
-        ...(options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+        ...(options.pushConfig ? { pushConfig: options.pushConfig } : options.pushEndpoint ? { pushConfig: { pushEndpoint: options.pushEndpoint } } : {}),
+        ...(options.deadLetterPolicy ? { deadLetterPolicy: options.deadLetterPolicy } : {}),
+        ...(options.retryPolicy ? { retryPolicy: options.retryPolicy } : {}),
       });
     },
     async publish(topic: string, data: string | Uint8Array, attributes?: Record<string, string>): Promise<string> {
@@ -128,6 +161,23 @@ export interface PubSubHelpers extends PubSubClient {
   emulatorHost: string;
 }
 
+// The official emulator ignores OIDC. Keep its push/retry/dead-letter engine,
+// but route authenticated deliveries through a local adapter in its container.
+function authenticatedPush(options: PubSubSubscriptionOptions, pushPort: number): PubSubSubscriptionOptions {
+  subscriptionOptions(options);
+  const push = options.pushConfig;
+  if (!push?.oidcToken) return options;
+  const config = Buffer.from(JSON.stringify({ endpoint: push.pushEndpoint, ...push.oidcToken })).toString("base64url");
+  return {
+    ...options, pushEndpoint: undefined,
+    pushConfig: { ...push, pushEndpoint: `http://127.0.0.1:${pushPort}/push/${config}` },
+  };
+}
+
+function withPushAuth(client: PubSubClient, pushPort: number): PubSubClient {
+  return { ...client, createSubscription: (id, options) => client.createSubscription(id, authenticatedPush(options, pushPort)) };
+}
+
 /** Google Cloud's real local Pub/Sub emulator, ready for Google client libraries.
  * Mount directly in services: { pubsub: pubsub({ topics: ["orders"] }) }.
  * Applications use their default pubsub.googleapis.com:443 endpoint with
@@ -137,6 +187,7 @@ export interface PubSubHelpers extends PubSubClient {
 export function pubsub(opts: PubSubOptions = {}) {
   const projectId = projectName(opts.projectId ?? "spectest");
   const port = opts.port ?? 8085;
+  const pushPort = port === 8086 ? 8087 : 8086;
   const hostname = opts.tls === false ? undefined : opts.tls?.hostname ?? "pubsub.googleapis.com";
   if (hostname !== undefined) {
     certificate([hostname]);
@@ -152,12 +203,20 @@ export function pubsub(opts: PubSubOptions = {}) {
     services: (): ServicesMap => {
       const emulator: ServiceDefinition = {
         image: { type: "registry", reference: opts.image ?? "gcr.io/google.com/cloudsdktool/google-cloud-cli:573.0.0-emulators" },
-        args: ["gcloud", "beta", "emulators", "pubsub", "start", `--project=${projectId}`, `--host-port=0.0.0.0:${port}`, "--quiet"],
+        args: ["sh", "-ec", `
+java_home=$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")
+cp "$java_home/lib/security/cacerts" /tmp/spectest-pubsub-cacerts
+keytool -importcert -noprompt -alias spectest-environment -keystore /tmp/spectest-pubsub-cacerts -storepass changeit -file "$NODE_EXTRA_CA_CERTS"
+export JAVA_TOOL_OPTIONS="-Djavax.net.ssl.trustStore=/tmp/spectest-pubsub-cacerts -Djavax.net.ssl.trustStorePassword=changeit \${JAVA_TOOL_OPTIONS:-}"
+python3 /opt/spectest-pubsub-push.py ${pushPort} &
+exec gcloud beta emulators pubsub start --project=${projectId} --host-port=0.0.0.0:${port} --quiet
+`],
+        files: [{ path: "/opt/spectest-pubsub-push.py", content: PUSH_ADAPTER }],
         ports: [port],
         ...(hostname ? { tls: [{ hostname, port, http2: true }] } : {}),
         readyCheck: { type: "http", port, path: `/v1/projects/${projectId}/topics`, timeoutSecs: 60 },
         setup: async ({ name }) => {
-          const client = pubsubClient(`http://${name}:${port}`, projectId);
+          const client = withPushAuth(pubsubClient(`http://${name}:${port}`, projectId), pushPort);
           for (const topic of topics) await client.createTopic(topic);
           for (const [id, options] of subscriptions) await client.createSubscription(id, options);
         },
@@ -165,8 +224,8 @@ export function pubsub(opts: PubSubOptions = {}) {
       return { emulator };
     },
     helpers: (ctx: ServiceHelpersContext): PubSubHelpers => ({
-      ...pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId,
-        async (input, init) => readRaw(await ctx.fetch(String(input), init)) as unknown as Response),
+      ...withPushAuth(pubsubClient(hostname ? `https://${hostname}` : `http://${ctx.name}:${port}`, projectId,
+        async (input, init) => readRaw(await ctx.fetch(String(input), init)) as unknown as Response), pushPort),
       emulatorHost: `${ctx.name}:${port}`,
     }),
     setup: async (ctx: ServiceSetupContext<PubSubHelpers>) => {