@fireemu/darwin-arm64 0.43.0 → 0.45.0

package/README.md

@@ -1,7 +1,7 @@
 # @fireemu/darwin-arm64
 
 The [fireemu](https://www.npmjs.com/package/fireemu) daemon built for `darwin-arm64`
-(Rust target `aarch64-apple-darwin`), version 0.43.0.
+(Rust target `aarch64-apple-darwin`), version 0.45.0.
 
 macOS 13 or newer on Apple silicon.
 

package/bin/fireemu

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/bin/fireemu
-size: 36876128 bytes
-sha256: a0e1688bf4e915c0be5d973019e3e643cb15a3f869e596cdf63937aeae506e7b
+size: 37455200 bytes
+sha256: 366bfa1748b43f36a77959b1571e4ba5fa5c86c908b1cd78b72becd39bfd7c75

package/bin/runner-node/index.mjs

@@ -724,14 +724,14 @@ function ignoredBlocking(base, eventType) {
   return ignored(base, "blocking", "unsupported", `blocking identity event ${eventType} is not served`);
 }
 
-// Products the official emulator has a trigger service for and fireemu does not serve.
+// Trigger families outside the served surface; exact supported types are handled first.
 // The event-type substring is matched the way `getServiceFromEventType` matches it.
 const DEFERRED_TRIGGER_PRODUCTS = [
   {
     match: (type) => type.includes("remoteconfig"),
     triggerType: "remoteConfig",
     scope: "deferred",
-    reason: "deferred: Remote Config has no emulator in the active supported surface",
+    reason: "deferred: only Remote Config update triggers are served by the local injection action",
   },
   {
     match: (type) => type.includes("dataconnect"),
@@ -768,6 +768,12 @@ function deferredProduct(type) {
 // firebase-functions v1 triggers: legacy event types and a resource pattern.
 function describeV1Event(base, type, resource, schedule, retry) {
   const v1 = { v1: true };
+  if (type === "google.firebase.remoteconfig.update") {
+    if (resource !== `projects/${process.env.GCLOUD_PROJECT}`) {
+      return ignored(base, "remoteConfig", "unsupported", "Remote Config resource must name the runtime project");
+    }
+    return { ...base, ...v1, retry, trigger: { type: "remoteConfig" } };
+  }
   const dbMatch = type.match(/^providers\/google\.firebase\.database\/eventTypes\/ref\.(create|update|delete|write)$/);
   if (dbMatch) {
     resource = triggerString(resource, "eventTrigger.resource", { optional: true, allowEmpty: true }) ?? "";
@@ -1020,6 +1026,9 @@ function describe(name, fn, instrumentation) {
           },
         };
       }
+      if (type === "google.firebase.remoteconfig.remoteConfig.v1.updated" && et.channel === undefined) {
+        return { ...base, trigger: { type: "remoteConfig" } };
+      }
       if (type === "google.cloud.pubsub.topic.v1.messagePublished") {
         const topic = triggerString(triggerRecord(et.eventFilters, "eventFilters").topic, "eventFilters.topic");
         const projectedTopic = topic.replace(/^.*\/topics\//, "");
@@ -1155,6 +1164,8 @@ const strictProfile = () => process.env.FIREEMU_HTTP_PROFILE === "strict";
 function v1Context(msg) {
   const event = msg.event;
   switch (msg.trigger) {
+    case "remoteConfig":
+      return event.context;
     case "database": {
       const operation = {created:"create",updated:"update",deleted:"delete",written:"write"}[event.type.split(".").at(-1)];
       const context = {
@@ -1497,6 +1508,8 @@ function firestoreProtoTimestamp(value) {
 function firestoreProtoFields(fields) {
   return Object.fromEntries(Object.entries(fields ?? {}).map(([key, value]) => {
     const converted = { ...value };
+    // protobufjs skips null members; the NullValue enum must be its numeric zero.
+    if (value.nullValue === null) converted.nullValue = 0;
     if (value.timestampValue !== undefined) converted.timestampValue = firestoreProtoTimestamp(value.timestampValue);
     if (value.mapValue !== undefined) converted.mapValue = { fields: firestoreProtoFields(value.mapValue.fields) };
     if (value.arrayValue !== undefined) {
@@ -1507,6 +1520,14 @@ function firestoreProtoFields(fields) {
 }
 
 function writtenFirestoreEvent(event) {
+  if (event.datacontenttype === "application/protobuf") {
+    // A single character repetition avoids stack growth; require the absolute end, including no trailing newline.
+    if (typeof event.data !== "string" || event.data.length % 4 !== 0 ||
+        !/^[A-Za-z0-9+/]*={0,2}(?![\s\S])/.test(event.data)) {
+      throw new Error("Firestore protobuf IPC data must be base64 text");
+    }
+    return { ...event, data: Buffer.from(event.data, "base64") };
+  }
   if (!["google.cloud.firestore.document.v1.written", "google.cloud.firestore.document.v1.written.withAuthContext"].includes(event.type) ||
       !event.datacontenttype?.includes("application/json")) return event;
   // The SDK's protobuf decoder derives missing snapshot paths from typed metadata,
@@ -1538,7 +1559,7 @@ async function invoke(functions, manifest, msg) {
     throw new Error("entry point does not match the function manifest");
   }
   if (msg.trigger !== spec.trigger?.type ||
-      !["schedule", "database", "firestore", "storage", "pubsub", "eventarc", "auth"].includes(msg.trigger)) {
+      !["schedule", "database", "firestore", "storage", "pubsub", "eventarc", "auth", "remoteConfig"].includes(msg.trigger)) {
     throw new Error("trigger does not match the function manifest");
   }
   const fn = functions.get(spec.entryPoint);
@@ -1581,6 +1602,7 @@ async function invoke(functions, manifest, msg) {
         case "storage":
           await fn({ ...msg.event, data: storageObjectInRecordedOrder(msg.event.data) });
           return;
+        case "remoteConfig":
         case "pubsub":
           await fn(msg.event);
           return;

package/bin/runner-python/fireemu_runner/appcheck.py

@@ -0,0 +1,255 @@
+"""Callable App Check: the Admin SDK verifies the token against the App Check emulator's keys.
+
+SECURITY-SENSITIVE. A Python callable checks the `X-Firebase-AppCheck` header itself, in the SDK's wrapper, with
+`firebase_admin.app_check.verify_token` (`firebase_functions/private/util.py`), which fetches Google's JWKS. The
+Python SDK has no switch to skip that check (Node's `skipTokenVerification`), and the daemon's callable trust
+boundary does not apply to it, so the runner makes the SDK's own check meaningful locally:
+
+- when the daemon names the App Check emulator's JWKS (`FIREEMU_APP_CHECK_JWKS_URL`, a loopback address), the
+  Admin SDK's App Check service is replaced, before any user code runs, by one that fetches keys from it alone, so
+  only a token the emulator's key signed verifies, and the runner tells the daemon the callables do not consume tokens (`consumeAppCheckToken:
+  disabled`, true: the SDK verifies with `consume=False`), which lets the daemon forward the header;
+- otherwise nothing is changed and the runner says nothing, so the daemon keeps removing the header before the
+  function and the SDK never fetches a key from Google.
+
+Anything but a loopback `http` URL is refused, so a stray value cannot make the runner fetch keys from elsewhere.
+
+The runner fetches the keys itself (`LoopbackKeyClient`) instead of leaving it to PyJWT's `PyJWKClient`, whose
+redirect and proxy behaviour depends on the PyJWT version (2.13.0, which the SDK's constraints allow, follows
+redirects). The client connects to a loopback address it resolved and checked, ignores proxy variables, treats every
+redirect as a failure, and bounds time and size. What the Python SDK checks of a token is the stock SDK's, plus what
+the emulator always does and the stock SDK leaves optional (`exp`, the exact issuer).
+
+Differences from Node, which the Functions page states: the Python SDK verifies against the keys alone, so it has no
+check of the daemon's current project epoch or app state (the Node callable trust boundary has one), and it is not
+instrumented, so it has no start-up self-test. The PyJWT floor below is the lowest version the tests ran against.
+"""
+
+import http.client
+import ipaddress
+import json
+import re
+import socket
+import threading
+import time
+from urllib.parse import urlsplit
+
+URL_VARIABLE = "FIREEMU_APP_CHECK_JWKS_URL"
+_LOOPBACK_NAMES = frozenset(("localhost",))
+
+
+def jwks_url(environ) -> str | None:
+    """The App Check emulator's JWKS URL from the daemon's environment, or None when it is absent or not loopback."""
+    value = environ.get(URL_VARIABLE)
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        parts = urlsplit(value)
+        port = parts.port  # raises for a port out of range
+        host = parts.hostname
+    except ValueError:
+        return None
+    if parts.scheme != "http" or host is None or parts.username is not None or parts.password is not None:
+        return None
+    if parts.fragment or not parts.path.startswith("/") or len(parts.path) < 2 or port is None:
+        return None
+    if host not in _LOOPBACK_NAMES:
+        try:
+            if not ipaddress.ip_address(host).is_loopback:
+                return None
+        except ValueError:
+            return None
+    return value
+
+
+MIN_PYJWT = (2, 10, 1)
+_REQUIRED_ATTRIBUTES = ("_JWKS_URL", "_APP_CHECK_HEADERS", "_decode_and_verify", "_has_valid_token_headers", "verify_token")
+_ISSUER = re.compile(r"https://firebaseappcheck\.googleapis\.com/([0-9]+)")
+
+
+def _pyjwt_supported() -> bool:
+    import jwt
+
+    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", str(getattr(jwt, "__version__", "")))
+    return match is not None and tuple(int(part) for part in match.groups()) >= MIN_PYJWT
+
+
+def _loopback_addresses(host: str, port: int) -> list[str]:
+    """The loopback addresses `host` names. Every address a name resolves to must be loopback, or none is used."""
+    literal = host.strip("[]")
+    try:
+        addresses = [ipaddress.ip_address(literal)]
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+        except OSError as error:
+            raise OSError(f"cannot resolve {host}") from error
+        addresses = [ipaddress.ip_address(info[4][0].split("%")[0]) for info in infos]
+    if not addresses or not all(address.is_loopback for address in addresses):
+        raise OSError(f"{host} is not a loopback address")
+    return [str(address) for address in addresses]
+
+
+class LoopbackKeyClient:
+    """Fetches and caches the App Check emulator's signing keys from one loopback URL, and nowhere else.
+
+    Same contract as `jwt.PyJWKClient.get_signing_key_from_jwt` (the object it returns has a `.key`), without any of
+    its transport: no redirect is followed (a 3xx is a failure), no proxy variable is read, the connection goes to a
+    loopback address the client resolved and checked itself, and time and size are bounded. A failure means no key,
+    so the token does not verify.
+    """
+
+    def __init__(self, url, *, timeout=5.0, max_bytes=256 * 1024, lifespan=21600, refresh_interval=1.0, headers=None):
+        self._url = url
+        self._timeout = timeout
+        self._max_bytes = max_bytes
+        self._lifespan = lifespan
+        self._refresh_interval = refresh_interval
+        self._headers = dict(headers or {})
+        self._lock = threading.Lock()
+        self._keys = {}
+        self._fetched_at = None
+        self._attempted_at = None
+
+    def _connect(self, addresses, port):
+        """A connection to the first of the checked loopback addresses that accepts one (`localhost` may list `::1`)."""
+        last = OSError("no address")
+        for address in addresses:
+            try:
+                return socket.create_connection((address, port), timeout=self._timeout)
+            except OSError as error:
+                last = error
+        raise last
+
+    def _fetch(self):
+        parts = urlsplit(self._url)
+        host, port = parts.hostname, parts.port
+        if parts.scheme != "http" or host is None or port is None:
+            raise OSError("the key URL is not a loopback http URL")
+        path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+        addresses = _loopback_addresses(host, port)
+        connection = http.client.HTTPConnection(host, port, timeout=self._timeout)
+        try:
+            connection.sock = self._connect(addresses, port)
+            connection.request("GET", path, headers={"Accept": "application/json", "Connection": "close", **self._headers})
+            response = connection.getresponse()
+            if response.status != 200:
+                raise OSError(f"the key server answered {response.status}")
+            body = response.read(self._max_bytes + 1)
+            if len(body) > self._max_bytes:
+                raise OSError("the key set is larger than the bound")
+        finally:
+            connection.close()
+        document = json.loads(body)
+        listed = document.get("keys") if isinstance(document, dict) else None
+        if not isinstance(listed, list):
+            raise ValueError("the key set has no keys list")
+        import jwt
+
+        keys = {}
+        for entry in listed:
+            if isinstance(entry, dict) and entry.get("kty") == "RSA" and isinstance(entry.get("kid"), str):
+                try:
+                    keys[entry["kid"]] = jwt.PyJWK(entry)
+                except Exception:  # a key that cannot be built is no key
+                    continue
+        return keys
+
+    def get_signing_key_from_jwt(self, token):
+        import jwt
+        from jwt.exceptions import PyJWKClientError
+
+        kid = jwt.get_unverified_header(token).get("kid")
+        if not isinstance(kid, str) or not kid:
+            raise PyJWKClientError("the token has no key id")
+        with self._lock:
+            now = time.monotonic()
+            stale = self._fetched_at is None or now - self._fetched_at > self._lifespan
+            if kid in self._keys and not stale:
+                return self._keys[kid]
+            if self._attempted_at is None or now - self._attempted_at >= self._refresh_interval:
+                self._attempted_at = now
+                try:
+                    self._keys = self._fetch()
+                    self._fetched_at = now
+                except Exception as error:
+                    self._keys, self._fetched_at = {}, None
+                    raise PyJWKClientError("the App Check keys could not be fetched") from error
+            if kid not in self._keys:
+                raise PyJWKClientError(f"unable to find a signing key that matches {kid!r}")
+            return self._keys[kid]
+
+
+def _emulator_service(stock, url: str):
+    """The Admin SDK's App Check service, keyed to `url` and without credentials or a way to reach Google.
+
+    The stock service builds an authorised HTTP client in its constructor (`app.credential.get_credential()`), which
+    only limited-use consumption uses; a runner has no Google credential, so the stock service cannot even verify.
+    This one is the same verifier (`verify_token`, the header and signature checks are the SDK's own methods) with
+    the keys fetched by `LoopbackKeyClient`, consumption refused, and two claim checks the emulator always satisfies.
+    The audience rule stays the stock SDK's (`projects/<projectId>`).
+    """
+    from firebase_admin import exceptions
+
+    class EmulatorAppCheckService(stock):
+        _JWKS_URL = url
+
+        def __init__(self, app):
+            project_id = app.project_id
+            if not project_id:
+                raise ValueError(
+                    "A project ID must be specified to access the App Check service. Either set the projectId "
+                    "option, use service account credentials, or set the GOOGLE_CLOUD_PROJECT environment variable."
+                )
+            self._project_id = project_id
+            self._scoped_project_id = "projects/" + project_id
+            self._jwks_client = LoopbackKeyClient(self._JWKS_URL, lifespan=21600, headers=self._APP_CHECK_HEADERS)
+            self._http_client = None
+
+        def _decode_and_verify(self, token, signing_key):
+            payload = super()._decode_and_verify(token, signing_key)
+            exp = payload.get("exp")
+            if isinstance(exp, bool) or not isinstance(exp, (int, float)):
+                raise ValueError('The provided App Check token has no "exp" (expiration) claim.')
+            issuer = payload.get("iss")
+            match = _ISSUER.fullmatch(issuer) if isinstance(issuer, str) else None
+            if match is None:
+                raise ValueError('The provided App Check token has an incorrect "iss" (issuer) claim.')
+            audience = payload.get("aud")
+            audiences = [audience] if isinstance(audience, str) else audience if isinstance(audience, list) else []
+            numbers = [item[len("projects/"):] for item in audiences if isinstance(item, str) and item.startswith("projects/") and item[len("projects/"):].isdigit()]
+            if any(number != match.group(1) for number in numbers):
+                raise ValueError('The provided App Check token has a project number in "aud" that is not its issuer\'s.')
+            subject = payload.get("sub")
+            if not isinstance(subject, str) or not subject:
+                # The stock SDK refuses a missing one and lets an empty one through.
+                raise ValueError('The provided App Check token has no "sub" (app ID) claim.')
+            return payload
+
+        def _verify_replay_protection(self, token):
+            raise exceptions.FailedPreconditionError(
+                "limited-use App Check token consumption is not available in fireemu (APP_CHECK_REPLAY_UNSUPPORTED)"
+            )
+
+    return EmulatorAppCheckService
+
+
+def install_jwks_hook(url: str) -> bool:
+    """Replaces the Admin SDK's App Check service with one keyed to `url`. False when this SDK is not the one that
+    replacement was written for, or PyJWT is older than the tested floor (the runner then announces nothing, and the
+    daemon keeps removing the header)."""
+    from firebase_admin import app_check
+
+    stock = getattr(app_check, "_AppCheckService", None)
+    if stock is None or not isinstance(getattr(stock, "_JWKS_URL", None), str):
+        return False
+    if not all(hasattr(stock, name) for name in _REQUIRED_ATTRIBUTES) or not _pyjwt_supported():
+        return False
+    app_check._AppCheckService = _emulator_service(stock, url)
+    return True
+
+
+def install_from_environment(environ) -> bool:
+    """Installs the hook when the daemon named a loopback JWKS URL; True when the SDK now verifies against it."""
+    url = jwks_url(environ)
+    return url is not None and install_jwks_hook(url)

package/bin/runner-python/fireemu_runner/bodies.py

@@ -0,0 +1,96 @@
+"""The text of an event's JSON body in the layouts the recorded deliveries had.
+
+Recorded 2026-11-04 (sandbox run PYCHECK-EVENTS-20261104-01, the raw twins; `tests/recorded_bodies.json`):
+
+- an Eventarc custom event: the publisher's own compact text, member order as published (51 and 48 bytes);
+- a Pub/Sub message: sorted compact JSON followed by a newline (348 and 382 bytes);
+- a Cloud Storage object: the object resource indented by two spaces, in the Cloud Storage JSON API member order, followed by a
+  newline (963 bytes).
+
+A Realtime Database event was not recorded. Numbers keep the spelling they have in the text the daemon framed (`1e-7`, `1e20`,
+`-0.0`): `Number` is a number as written. Characters are written as UTF-8, not as `\\u` escapes (the recorded bodies hold none).
+"""
+
+import json
+
+
+class Number(str):
+    """A JSON number as it was written."""
+
+
+def parse_keeping_numbers(text: str):
+    """The value of a JSON text with every number kept as `Number`."""
+    return json.loads(text, parse_int=Number, parse_float=Number)
+
+
+def write(value, *, sort_keys: bool = False, indent: int | None = None, level: int = 0) -> str:
+    """JSON text of `value`: compact, or with each member on its own line indented by `indent` spaces."""
+    if isinstance(value, Number):
+        return str(value)
+    if isinstance(value, dict):
+        members = sorted(value.items()) if sort_keys else list(value.items())
+        if not members:
+            return "{}"
+        parts = [f"{json.dumps(str(k), ensure_ascii=False)}{': ' if indent else ':'}{write(v, sort_keys=sort_keys, indent=indent, level=level + 1)}" for k, v in members]
+        return _join("{", parts, "}", indent, level)
+    if isinstance(value, list):
+        if not value:
+            return "[]"
+        return _join("[", [write(v, sort_keys=sort_keys, indent=indent, level=level + 1) for v in value], "]", indent, level)
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _join(open_: str, parts: list, close: str, indent: int | None, level: int) -> str:
+    if not indent:
+        return open_ + ",".join(parts) + close
+    inner = "\n" + " " * (indent * (level + 1))
+    return open_ + inner + ("," + inner).join(parts) + "\n" + " " * (indent * level) + close
+
+
+def compact(value) -> str:
+    return write(value)
+
+
+def pubsub_layout(value) -> str:
+    """Sorted compact JSON and a newline: what Pub/Sub's push delivery sent (recorded)."""
+    return write(value, sort_keys=True) + "\n"
+
+
+# The member order of a Cloud Storage object resource as the recorded body had it. Members the recording does not show are
+# UNRECORDED: they follow the known ones in alphabetical order.
+_GCS_OBJECT_ORDER = (
+    "kind",
+    "id",
+    "selfLink",
+    "name",
+    "bucket",
+    "generation",
+    "metageneration",
+    "contentType",
+    "timeCreated",
+    "updated",
+    "storageClass",
+    "timeStorageClassUpdated",
+    "size",
+    "md5Hash",
+    "mediaLink",
+    "crc32c",
+    "etag",
+)
+
+
+def _sorted_deep(value):
+    if isinstance(value, dict):
+        return {k: _sorted_deep(v) for k, v in sorted(value.items())}
+    if isinstance(value, list):
+        return [_sorted_deep(v) for v in value]
+    return value
+
+
+def storage_layout(value) -> str:
+    """The object resource in the API's member order, indented by two spaces, and a newline (recorded for the known members)."""
+    if isinstance(value, dict):
+        known = [(k, _sorted_deep(value[k])) for k in _GCS_OBJECT_ORDER if k in value]
+        rest = [(k, _sorted_deep(v)) for k, v in sorted(value.items()) if k not in _GCS_OBJECT_ORDER]
+        value = dict(known + rest)
+    return write(value, indent=2) + "\n"

package/bin/runner-python/fireemu_runner/diagnostics.py

@@ -0,0 +1,36 @@
+"""Turning a failure into text without trusting the failure.
+
+An exception raised by user code can run user code when it is turned into text (`__str__`, `__repr__`, a
+chained cause). With one process environment shared by every invocation, that text must be made while the
+failing invocation still holds its place in the secret gate, and a failure to make it must not lose the result.
+"""
+
+import inspect
+import traceback
+
+
+def describe(error: BaseException) -> tuple[str, str]:
+    """`(traceback text, short text)` of `error`; never raises, whatever the error's methods do."""
+    try:
+        diagnostic = "".join(traceback.format_exception(error))
+    except BaseException:
+        diagnostic = f"{type(error).__name__}: (the error could not be formatted)\n"
+    try:
+        text = str(error) or type(error).__name__
+    except BaseException:
+        text = type(error).__name__
+    return diagnostic, text
+
+
+ASYNC_HANDLER = (
+    "the function is an async handler: the Python SDK never awaits a handler, so its body would never run "
+    "(production skips it silently); declare it with def"
+)
+
+
+def is_async_handler(function) -> bool:
+    """Whether the user's function behind an SDK wrapper is a coroutine function."""
+    try:
+        return inspect.iscoroutinefunction(inspect.unwrap(function))
+    except ValueError:  # a cycle of __wrapped__ links: not something this can decide
+        return False

package/bin/runner-python/fireemu_runner/dispatch.py

@@ -2,29 +2,46 @@
 
 import os
 import threading
-import traceback
-
-from .events import (
-    database_cloud_event,
-    eventarc_cloud_event,
-    firestore_cloud_event,
-    pubsub_cloud_event,
-    storage_cloud_event,
-)
+
+from cloudevents.http import from_http
+
+from .events import database_request, eventarc_request, firestore_request, pubsub_request, storage_request
+from .request_view import delivery_request
+from .diagnostics import ASYNC_HANDLER, describe, is_async_handler
+from .environment import EnvironmentGate
 from .framing import FrameWriter
+from .scheduler import SchedulerFailure, deliver_schedule
 
 MAX_ACTIVE_INVOCATIONS = 4096
 _MAX_ERROR_CHARS = 4096
 _MAX_DIAGNOSTIC_CHARS = 256 * 1024
 
-# Trigger types that arrive as an `invoke` frame, and how each becomes the handler's argument.
-_EVENT_ADAPTERS = {
-    "firestore": firestore_cloud_event,
-    "pubsub": pubsub_cloud_event,
-    "storage": storage_cloud_event,
-    "eventarc": eventarc_cloud_event,
-    "database": database_cloud_event,
+# Trigger types that arrive as an `invoke` frame whose function takes a CloudEvent, and the adapter that builds the request
+# (headers and body) that delivers it.
+_CLOUD_EVENTS = {
+    "firestore": firestore_request,
+    "pubsub": pubsub_request,
+    "storage": storage_request,
+    "eventarc": eventarc_request,
+    "database": database_request,
 }
+# A Gen2 scheduled function is an HTTP function: the SDK wrapper takes the scheduler's request.
+_TRIGGERS = frozenset((*_CLOUD_EVENTS, "schedule"))
+
+
+def _deliver(trigger: str, function, event, raw_data: str | None = None) -> None:
+    if trigger == "schedule":
+        deliver_schedule(function, event.get("data") if isinstance(event, dict) else None)
+    else:
+        delivery = _CLOUD_EVENTS[trigger](event, raw_data)
+        # As functions-framework does: the function runs inside the request that delivers the event. The event is built
+        # from the encoding the adapters have always used; the request shows the layout the recorded delivery had.
+        with delivery_request(delivery.headers, delivery.request_body, event):
+            function(from_http(delivery.headers, delivery.event_body))
+
+
+# What `FUNCTION_SIGNATURE_TYPE` says for each (the Node runner's `signatureType`).
+_SIGNATURE_TYPES = {"schedule": "http"}
 
 
 def _bound(text: str, limit: int) -> str:
@@ -34,7 +51,8 @@ def _bound(text: str, limit: int) -> str:
 class Dispatcher:
     """Runs `invoke` frames against the functions the manifest serves."""
 
-    def __init__(self, functions: dict, manifest: dict, writer: FrameWriter):
+    def __init__(self, functions: dict, manifest: dict, writer: FrameWriter, gate: EnvironmentGate | None = None):
+        self._gate = gate if gate is not None else EnvironmentGate({})
         self._functions = functions
         self._specs = {spec["name"]: spec for spec in manifest["functions"]}
         self._writer = writer
@@ -48,7 +66,7 @@ class Dispatcher:
         if "entryPoint" in message and message["entryPoint"] != spec["entryPoint"]:
             raise LookupError("entry point does not match the function manifest")
         trigger = spec["trigger"]["type"]
-        if message["trigger"] != trigger or trigger not in _EVENT_ADAPTERS:
+        if message["trigger"] != trigger or trigger not in _TRIGGERS:
             raise LookupError("trigger does not match the function manifest")
         function = self._functions.get(spec["entryPoint"])
         if not callable(function):
@@ -66,22 +84,41 @@ class Dispatcher:
         """Runs one invoke frame on a new thread; the caller has reserved a slot with `reserve`."""
         threading.Thread(target=self._run, args=(message,), daemon=True, name=f"invoke-{message['invocationId']}").start()
 
-    def _run(self, message: dict) -> None:
-        invocation = message["invocationId"]
+    def _deliver_held(self, message: dict) -> tuple[str, str] | None:
+        """Runs the invocation and returns `(diagnostic, text)` of its failure, or None.
+
+        The failure is described here, inside the gate: turning an exception into text can run user code
+        (`__str__`), and after the invocation leaves the gate another invocation's secrets may be present.
+        """
         try:
+            spec, function = self._check(message)
+        except BaseException as error:  # not user code, but a malformed frame: still answered, never raised
+            return describe(error)
+        if is_async_handler(function):
+            return ASYNC_HANDLER, ASYNC_HANDLER
+        with self._gate.hold(spec.get("platformOptions", {}).get("secrets")):
             try:
-                spec, function = self._check(message)
                 # One process serves the whole codebase, so these name the invocation that started most
                 # recently, not a fixed target (the design memo, section 5).
                 os.environ["FUNCTION_TARGET"] = spec["entryPoint"]
-                os.environ["FUNCTION_SIGNATURE_TYPE"] = "cloudevent"
+                os.environ["FUNCTION_SIGNATURE_TYPE"] = _SIGNATURE_TYPES.get(message["trigger"], "cloudevent")
                 os.environ["K_SERVICE"] = spec["name"]
-                function(_EVENT_ADAPTERS[message["trigger"]](message["event"]))
-                result = {"type": "result", "invocationId": invocation, "ok": True}
+                _deliver(message["trigger"], function, message["event"], message.get("rawEventData"))
             except BaseException as error:  # a SystemExit in user code must still answer the daemon
-                diagnostic = "".join(traceback.format_exception(error))
+                diagnostic, text = describe(error)
+                # A scheduled attempt the SDK wrapper answered 500 has been logged by the SDK; its status is the news.
+                return (str(error) if isinstance(error, SchedulerFailure) else diagnostic), text
+        return None
+
+    def _run(self, message: dict) -> None:
+        invocation = message["invocationId"]
+        try:
+            failure = self._deliver_held(message)
+            if failure is None:
+                result = {"type": "result", "invocationId": invocation, "ok": True}
+            else:
+                diagnostic, text = failure
                 self._send_log("error", f"{message['function']}: {diagnostic}", invocation, message["function"])
-                text = str(error) or type(error).__name__
                 result = {"type": "result", "invocationId": invocation, "ok": False, "error": _bound(text, _MAX_ERROR_CHARS)}
             self._writer.write(result)
         finally: