@beeos-ai/device-agent 0.4.3 → 0.5.0

package/dist/resources/registry.js

@@ -0,0 +1,107 @@
+/**
+ * Resource Resolver Registry — owns the parser/resolver dispatch and
+ * the `resolveAll(task)` orchestration entry point.
+ *
+ * Lifecycle:
+ *  1. Bootstrap constructs one registry per AgentHost.
+ *  2. AgentHost.submitTask calls `parseAll(prompt)` to extract refs.
+ *  3. For each ref, registry picks the first matching `ResourceResolver`
+ *     and delegates resolution. Parallel where possible.
+ *  4. Failures are isolated: one bad URL must not poison the rest of
+ *     the task. The host falls back to the original prompt only when
+ *     every resolution failed (or zero refs were found).
+ *
+ * The registry stays explicit about its dependencies (`ResolverContext`)
+ * so unit tests can wire it up without bootstrap.
+ */
+export class ResourceResolverRegistry {
+    parsers;
+    resolvers;
+    constructor(opts) {
+        this.parsers = [...opts.parsers];
+        this.resolvers = [...opts.resolvers];
+    }
+    /** Run every registered parser; deduplicate by JSON-canonical key. */
+    parseAll(task) {
+        if (!task)
+            return [];
+        const seen = new Set();
+        const out = [];
+        for (const p of this.parsers) {
+            let refs;
+            try {
+                refs = p.parse(task);
+            }
+            catch {
+                // A misbehaving parser must NOT crash the whole task.
+                continue;
+            }
+            for (const ref of refs) {
+                const key = stableKey(ref);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(ref);
+            }
+        }
+        return out;
+    }
+    /**
+     * Resolve every ref present in the task. Returns successfully
+     * resolved assets; failures are surfaced via the `errors` array but
+     * never thrown — the AgentHost is responsible for falling back to
+     * the original prompt when no asset survived.
+     */
+    async resolveAll(task, ctx) {
+        const refs = this.parseAll(task);
+        if (refs.length === 0) {
+            return { assets: [], errors: [], skipped: [] };
+        }
+        const work = refs.map(async (ref) => {
+            const resolver = this.pick(ref);
+            if (!resolver) {
+                return { kind: "skip", ref };
+            }
+            try {
+                const asset = await resolver.resolve(ref, ctx);
+                return { kind: "ok", asset };
+            }
+            catch (e) {
+                return { kind: "err", ref, error: e };
+            }
+        });
+        const results = await Promise.all(work);
+        const out = { assets: [], errors: [], skipped: [] };
+        for (const r of results) {
+            if (r.kind === "ok")
+                out.assets.push(r.asset);
+            else if (r.kind === "err")
+                out.errors.push({ ref: r.ref, error: r.error });
+            else
+                out.skipped.push(r.ref);
+        }
+        return out;
+    }
+    pick(ref) {
+        for (const r of this.resolvers) {
+            if (r.match(ref))
+                return r;
+        }
+        return undefined;
+    }
+}
+function stableKey(ref) {
+    switch (ref.kind) {
+        case "url":
+            return `url:${ref.url}`;
+        case "file":
+            return `file:${ref.path}`;
+        case "text":
+            return `text:${ref.text}`;
+        case "coordinate":
+            return `coord:${ref.lat},${ref.lon}`;
+        case "beeos-file":
+            return `beeos-file:${ref.fileId}`;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/resources/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/resources/registry.ts"],"names":[],"mappings":"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"}

package/dist/resources/resolvers/beeos-file-resolver.d.ts

@@ -0,0 +1,62 @@
+/**
+ * BeeOS File Resolver — turn a `beeos-file://<fileId>` ref into a
+ * device-local asset.
+ *
+ * The web UI emits an ACP `resource_link` block with
+ * `uri: "beeos-file://<fileId>"` for every file the user uploads via
+ * the chat input. The fileId addresses an opaque blob in the platform's
+ * file storage (S3 / MinIO). To get the bytes onto the device this
+ * resolver:
+ *
+ *   1. Calls the Agent Gateway's `GET /api/v1/agent/files/{id}/resolve`
+ *      (Ed25519-authenticated) which returns a short-lived presigned
+ *      download URL plus mime/name/size metadata.
+ *   2. Constructs a synthetic `kind: "url"` ref pointing at the
+ *      presigned URL and delegates to the supplied `UrlResolver`. The
+ *      url resolver does the heavy lifting (streaming download, MIME
+ *      whitelist, content-length cap, push via MCP fileWrite, Android
+ *      MediaScanner broadcast).
+ *   3. Rewrites the returned `ResolvedAsset` so the public fields refer
+ *      to the original `beeos-file://<fileId>` form. Most importantly,
+ *      the SigV4-signed presigned URL is NEVER copied into `sourceUrl`
+ *      or any logged field — it would leak into LLM context (via the
+ *      augmenter) and structured logs.
+ *
+ * The presigned URL points at the platform's object store. In production
+ * that's a public S3/MinIO host; in local dev it's `localhost:9000`.
+ * SSRF defenses (`denyPrivateIp`) MUST therefore be turned off for the
+ * delegated fetch — the resolve endpoint is already an authenticated,
+ * server-vended URL, so the loopback target is by-design and not a
+ * vector. MIME / size / cancellation defenses still apply.
+ */
+import type { ResolvedAsset, ResolverContext, ResourceRef, ResourceResolver } from "../types.js";
+import { type UrlResolver } from "./url-resolver.js";
+import { type AgentGatewayIdentity, type ResolvedAgentFile } from "../../adapters/agent-gateway-client.js";
+export interface BeeosFileResolverOptions {
+    /** Agent Gateway base URL, e.g. `http://localhost:8083` or `https://agent-gw.beeos.ai`. */
+    agentGatewayUrl: string;
+    /** Ed25519 identity used to sign the resolve request. */
+    identity: AgentGatewayIdentity;
+    /** UrlResolver instance to delegate the actual download/push pipeline to. */
+    urlResolver: UrlResolver;
+    /** Test seam — Agent Gateway resolve endpoint timeout. Default 10s. */
+    resolveTimeoutMs?: number;
+    /** Test seam — replaces `resolveAgentFile` for unit tests. */
+    resolveImpl?: (args: {
+        agentGatewayUrl: string;
+        identity: AgentGatewayIdentity;
+        fileId: string;
+        timeoutMs?: number;
+    }) => Promise<ResolvedAgentFile>;
+}
+export declare class BeeosFileResolver implements ResourceResolver {
+    readonly name = "beeos-file";
+    private readonly agentGatewayUrl;
+    private readonly identity;
+    private readonly urlResolver;
+    private readonly resolveTimeoutMs;
+    private readonly resolveImpl;
+    constructor(opts: BeeosFileResolverOptions);
+    match(ref: ResourceRef): boolean;
+    resolve(ref: ResourceRef, ctx: ResolverContext): Promise<ResolvedAsset>;
+}

package/dist/resources/resolvers/beeos-file-resolver.js

@@ -0,0 +1,109 @@
+/**
+ * BeeOS File Resolver — turn a `beeos-file://<fileId>` ref into a
+ * device-local asset.
+ *
+ * The web UI emits an ACP `resource_link` block with
+ * `uri: "beeos-file://<fileId>"` for every file the user uploads via
+ * the chat input. The fileId addresses an opaque blob in the platform's
+ * file storage (S3 / MinIO). To get the bytes onto the device this
+ * resolver:
+ *
+ *   1. Calls the Agent Gateway's `GET /api/v1/agent/files/{id}/resolve`
+ *      (Ed25519-authenticated) which returns a short-lived presigned
+ *      download URL plus mime/name/size metadata.
+ *   2. Constructs a synthetic `kind: "url"` ref pointing at the
+ *      presigned URL and delegates to the supplied `UrlResolver`. The
+ *      url resolver does the heavy lifting (streaming download, MIME
+ *      whitelist, content-length cap, push via MCP fileWrite, Android
+ *      MediaScanner broadcast).
+ *   3. Rewrites the returned `ResolvedAsset` so the public fields refer
+ *      to the original `beeos-file://<fileId>` form. Most importantly,
+ *      the SigV4-signed presigned URL is NEVER copied into `sourceUrl`
+ *      or any logged field — it would leak into LLM context (via the
+ *      augmenter) and structured logs.
+ *
+ * The presigned URL points at the platform's object store. In production
+ * that's a public S3/MinIO host; in local dev it's `localhost:9000`.
+ * SSRF defenses (`denyPrivateIp`) MUST therefore be turned off for the
+ * delegated fetch — the resolve endpoint is already an authenticated,
+ * server-vended URL, so the loopback target is by-design and not a
+ * vector. MIME / size / cancellation defenses still apply.
+ */
+import { ResolverError } from "./url-resolver.js";
+import { resolveAgentFile, } from "../../adapters/agent-gateway-client.js";
+export class BeeosFileResolver {
+    name = "beeos-file";
+    agentGatewayUrl;
+    identity;
+    urlResolver;
+    resolveTimeoutMs;
+    resolveImpl;
+    constructor(opts) {
+        this.agentGatewayUrl = opts.agentGatewayUrl;
+        this.identity = opts.identity;
+        this.urlResolver = opts.urlResolver;
+        this.resolveTimeoutMs = opts.resolveTimeoutMs ?? 10_000;
+        this.resolveImpl = opts.resolveImpl ?? resolveAgentFile;
+    }
+    match(ref) {
+        return ref.kind === "beeos-file";
+    }
+    async resolve(ref, ctx) {
+        if (ref.kind !== "beeos-file") {
+            throw new ResolverError("fetch_error", `BeeosFileResolver: unsupported ref kind ${ref.kind}`);
+        }
+        if (ctx.abortSignal.aborted) {
+            throw new ResolverError("aborted", "resolve aborted before start");
+        }
+        let presigned;
+        try {
+            presigned = await this.resolveImpl({
+                agentGatewayUrl: this.agentGatewayUrl,
+                identity: this.identity,
+                fileId: ref.fileId,
+                timeoutMs: this.resolveTimeoutMs,
+            });
+        }
+        catch (e) {
+            throw new ResolverError("fetch_error", `agent-gateway resolve failed for ${ref.fileId}: ${e.message}`, { fileId: ref.fileId });
+        }
+        if (!presigned.downloadUrl) {
+            throw new ResolverError("fetch_error", `agent-gateway returned empty downloadUrl for ${ref.fileId}`, { fileId: ref.fileId });
+        }
+        // The presigned URL points at the platform's object store
+        // (S3/MinIO). It's a server-vended URL we already trust because
+        // the resolve endpoint is Ed25519-authenticated; loopback in dev
+        // is by-design, so we turn off `denyPrivateIp` for the delegated
+        // fetch. MIME / size / cancellation defenses are unchanged.
+        //
+        // We also rewrite progress events from the inner UrlResolver so
+        // they carry the OUTER `beeos-file` ref shape. UrlResolver emits
+        // `phase: start/update/end` events with `ref: { kind: "url",
+        // url: <presigned> }` — those events flow into the AgentHost's
+        // `task:tool` stream and ultimately into the chat-UI tool card,
+        // which would leak the SigV4 token. Rewriting the ref keeps the
+        // progress UX (downloaded/total bytes, success/failure) intact
+        // while showing only the opaque `beeos-file://<fileId>` identity.
+        const outerEmit = ctx.emitProgress;
+        const innerCtx = {
+            ...ctx,
+            denyPrivateIp: false,
+            emitProgress: outerEmit
+                ? (ev) => outerEmit({ ...ev, ref })
+                : undefined,
+        };
+        const innerRef = { kind: "url", url: presigned.downloadUrl };
+        const inner = await this.urlResolver.resolve(innerRef, innerCtx);
+        // Strip the SigV4 token — the presigned URL must NEVER reach
+        // augmenter / logs / LLM context. Replace `ref` and `sourceUrl`
+        // with the opaque `beeos-file://<fileId>` form so downstream
+        // consumers can still correlate (telemetry, augmenter rendering)
+        // without exposing the presigned URL.
+        return {
+            ...inner,
+            ref,
+            sourceUrl: `beeos-file://${ref.fileId}`,
+        };
+    }
+}
+//# sourceMappingURL=beeos-file-resolver.js.map

package/dist/resources/resolvers/beeos-file-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beeos-file-resolver.js","sourceRoot":"","sources":["../../../src/resources/resolvers/beeos-file-resolver.ts"],"names":[],"mappings":"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"}

package/dist/resources/resolvers/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolver error vocabulary — kept as a closed enum so Prometheus
+ * counters never leak high-cardinality strings, and so the AgentHost
+ * can dispatch on a finite set of structured failure modes.
+ *
+ * The labels here align 1:1 with `ResolveOutcomeLabel` in `types.ts`;
+ * this module is the source of truth for the *error* subset (and `success`
+ * lives at the call site as a sentinel — never thrown).
+ */
+export type ResolverErrorCode = "fetch_error" | "push_error" | "scanner_failed" | "disallowed_scheme" | "oversized" | "timeout" | "private_ip_blocked" | "dns_rebind_blocked" | "disallowed_mime" | "disk_pressure" | "aborted";
+export declare const AGENT_HOST_ERROR_LABELS: Record<ResolverErrorCode, string>;

package/dist/resources/resolvers/errors.js

@@ -0,0 +1,23 @@
+/**
+ * Resolver error vocabulary — kept as a closed enum so Prometheus
+ * counters never leak high-cardinality strings, and so the AgentHost
+ * can dispatch on a finite set of structured failure modes.
+ *
+ * The labels here align 1:1 with `ResolveOutcomeLabel` in `types.ts`;
+ * this module is the source of truth for the *error* subset (and `success`
+ * lives at the call site as a sentinel — never thrown).
+ */
+export const AGENT_HOST_ERROR_LABELS = {
+    fetch_error: "fetch_error",
+    push_error: "push_error",
+    scanner_failed: "scanner_failed",
+    disallowed_scheme: "disallowed_scheme",
+    oversized: "oversized",
+    timeout: "timeout",
+    private_ip_blocked: "private_ip_blocked",
+    dns_rebind_blocked: "dns_rebind_blocked",
+    disallowed_mime: "disallowed_mime",
+    disk_pressure: "disk_pressure",
+    aborted: "aborted",
+};
+//# sourceMappingURL=errors.js.map

package/dist/resources/resolvers/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/resources/resolvers/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,MAAM,CAAC,MAAM,uBAAuB,GAAsC;IACxE,WAAW,EAAE,aAAa;IAC1B,UAAU,EAAE,YAAY;IACxB,cAAc,EAAE,gBAAgB;IAChC,iBAAiB,EAAE,mBAAmB;IACtC,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;IAClB,kBAAkB,EAAE,oBAAoB;IACxC,kBAAkB,EAAE,oBAAoB;IACxC,eAAe,EAAE,iBAAiB;IAClC,aAAa,EAAE,eAAe;IAC9B,OAAO,EAAE,SAAS;CACnB,CAAC"}

package/dist/resources/resolvers/mime-table.d.ts

@@ -0,0 +1,41 @@
+/**
+ * MIME → file-extension whitelist.
+ *
+ * SECURITY: this module is the SOLE source of file extensions used by
+ * the URL resolver. Extensions are NEVER derived from URL paths —
+ * doing so opens a path-traversal / extension-injection vector when
+ * the upstream serves a `.html` URL with `Content-Type: image/jpeg`.
+ *
+ * Two surfaces:
+ *   - `ALLOWED_MIMES` — exact MIME strings we accept.
+ *   - `ALLOWED_MIME_PREFIXES` — type/subtype prefixes (`image/`,
+ *     `video/`, `audio/`) for which we accept any subtype on the
+ *     condition that the resulting `mapMimeToExt` returns a real ext.
+ *
+ * A MIME is "allowed" iff:
+ *   1. It appears in `ALLOWED_MIMES` OR matches a prefix in
+ *      `ALLOWED_MIME_PREFIXES`, AND
+ *   2. `mapMimeToExt` returns a non-null extension.
+ *
+ * Add new entries by extending BOTH `ALLOWED_MIMES` (or appending to
+ * `ALLOWED_MIME_PREFIXES`) AND `MIME_TO_EXT`. Adding only one side is
+ * a bug — the resolver will accept the MIME but reject the resource
+ * for not having a whitelisted extension, leading to confusing errors.
+ */
+/**
+ * Strict whitelist — every entry maps to exactly one extension. Adding
+ * a new entry requires explicit security review (no dynamic
+ * extensions, no falling back to URL-path extension parsing).
+ */
+export declare const MIME_TO_EXT: Record<string, string>;
+/** Exact-match MIMEs (a strict subset of `MIME_TO_EXT` keys). */
+export declare const ALLOWED_MIMES: ReadonlySet<string>;
+/**
+ * Prefix-match MIMEs. The resolver still rejects the request if the
+ * `mapMimeToExt` lookup returns null, so adding a prefix here is safe.
+ *
+ * `application/*` is intentionally NOT a prefix — we want strict allow-
+ * listing for application subtypes (executables, installers, archives).
+ */
+export declare const ALLOWED_MIME_PREFIXES: readonly string[];
+export declare function mapMimeToExt(mime: string): string | null;

package/dist/resources/resolvers/mime-table.js

@@ -0,0 +1,92 @@
+/**
+ * MIME → file-extension whitelist.
+ *
+ * SECURITY: this module is the SOLE source of file extensions used by
+ * the URL resolver. Extensions are NEVER derived from URL paths —
+ * doing so opens a path-traversal / extension-injection vector when
+ * the upstream serves a `.html` URL with `Content-Type: image/jpeg`.
+ *
+ * Two surfaces:
+ *   - `ALLOWED_MIMES` — exact MIME strings we accept.
+ *   - `ALLOWED_MIME_PREFIXES` — type/subtype prefixes (`image/`,
+ *     `video/`, `audio/`) for which we accept any subtype on the
+ *     condition that the resulting `mapMimeToExt` returns a real ext.
+ *
+ * A MIME is "allowed" iff:
+ *   1. It appears in `ALLOWED_MIMES` OR matches a prefix in
+ *      `ALLOWED_MIME_PREFIXES`, AND
+ *   2. `mapMimeToExt` returns a non-null extension.
+ *
+ * Add new entries by extending BOTH `ALLOWED_MIMES` (or appending to
+ * `ALLOWED_MIME_PREFIXES`) AND `MIME_TO_EXT`. Adding only one side is
+ * a bug — the resolver will accept the MIME but reject the resource
+ * for not having a whitelisted extension, leading to confusing errors.
+ */
+/**
+ * Strict whitelist — every entry maps to exactly one extension. Adding
+ * a new entry requires explicit security review (no dynamic
+ * extensions, no falling back to URL-path extension parsing).
+ */
+export const MIME_TO_EXT = {
+    // images
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/png": "png",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/heic": "heic",
+    "image/heif": "heif",
+    "image/avif": "avif",
+    "image/svg+xml": "svg",
+    "image/bmp": "bmp",
+    // video
+    "video/mp4": "mp4",
+    "video/quicktime": "mov",
+    "video/webm": "webm",
+    "video/3gpp": "3gp",
+    "video/x-matroska": "mkv",
+    // audio
+    "audio/mpeg": "mp3",
+    "audio/mp4": "m4a",
+    "audio/aac": "aac",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/ogg": "ogg",
+    "audio/webm": "weba",
+    "audio/flac": "flac",
+    // documents
+    "application/pdf": "pdf",
+    "application/zip": "zip",
+    "application/vnd.android.package-archive": "apk",
+    "application/msword": "doc",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+    "application/vnd.ms-excel": "xls",
+    "application/vnd.ms-powerpoint": "ppt",
+    // text
+    "text/plain": "txt",
+    "text/csv": "csv",
+};
+/** Exact-match MIMEs (a strict subset of `MIME_TO_EXT` keys). */
+export const ALLOWED_MIMES = new Set(Object.keys(MIME_TO_EXT));
+/**
+ * Prefix-match MIMEs. The resolver still rejects the request if the
+ * `mapMimeToExt` lookup returns null, so adding a prefix here is safe.
+ *
+ * `application/*` is intentionally NOT a prefix — we want strict allow-
+ * listing for application subtypes (executables, installers, archives).
+ */
+export const ALLOWED_MIME_PREFIXES = [
+    "image/",
+    "video/",
+    "audio/",
+];
+export function mapMimeToExt(mime) {
+    const lower = mime.toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(MIME_TO_EXT, lower)) {
+        return MIME_TO_EXT[lower];
+    }
+    return null;
+}
+//# sourceMappingURL=mime-table.js.map

package/dist/resources/resolvers/mime-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime-table.js","sourceRoot":"","sources":["../../../src/resources/resolvers/mime-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAA2B;IACjD,SAAS;IACT,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,MAAM;IACpB,eAAe,EAAE,KAAK;IACtB,WAAW,EAAE,KAAK;IAElB,QAAQ;IACR,WAAW,EAAE,KAAK;IAClB,iBAAiB,EAAE,KAAK;IACxB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,KAAK;IACnB,kBAAkB,EAAE,KAAK;IAEzB,QAAQ;IACR,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,aAAa,EAAE,KAAK;IACpB,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,MAAM;IAEpB,YAAY;IACZ,iBAAiB,EAAE,KAAK;IACxB,iBAAiB,EAAE,KAAK;IACxB,yCAAyC,EAAE,KAAK;IAChD,oBAAoB,EAAE,KAAK;IAC3B,yEAAyE,EAAE,MAAM;IACjF,mEAAmE,EAAE,MAAM;IAC3E,2EAA2E,EAAE,MAAM;IACnF,0BAA0B,EAAE,KAAK;IACjC,+BAA+B,EAAE,KAAK;IAEtC,OAAO;IACP,YAAY,EAAE,KAAK;IACnB,UAAU,EAAE,KAAK;CAClB,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;AAEpF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,QAAQ;IACR,QAAQ;IACR,QAAQ;CACT,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,CAAC;QAC7D,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/resources/resolvers/url-resolver.d.ts

@@ -0,0 +1,85 @@
+/**
+ * URL Resolver — fetch HTTP(S) URLs and push them onto the device.
+ *
+ * Phase 1 / Pillar 1 of the GUI-Shortcut Hybrid Plan.
+ *
+ * Pipeline:
+ *
+ *   1. validate scheme  — `http` / `https` only (allowedSchemes).
+ *   2. SSRF check       — DNS resolve the hostname; reject any private
+ *                          / loopback / link-local / multicast IP.
+ *   3. fetch (streaming) — chunk-by-chunk with running size cap and
+ *                          AbortSignal merge. Validates Content-Type
+ *                          against the platform-supported MIME table.
+ *   4. DNS-rebind check — after the body has been read, re-resolve the
+ *                          hostname and assert at least one returned
+ *                          IP overlaps with the IP we accepted in (2).
+ *   5. choose ext       — strictly via Content-Type → ext mapping.
+ *                          Path-derived extensions are NEVER trusted.
+ *   6. choose target    — `ctx.device.resolveWellKnownDir(mime)` picks
+ *                          the platform-appropriate directory.
+ *   7. push             — `ctx.mcp.fileWrite(remotePath, bytes)`.
+ *   8. media-scan       — Android only: `touch -d now <path> &&
+ *                          am broadcast -a MEDIA_SCANNER_SCAN_FILE`
+ *                          so Gallery / WeChat / Photos see it as
+ *                          fresh and orderable. Best-effort; failure
+ *                          does NOT fail the resolve.
+ *
+ * All four SSRF defenses operate on the same `ResolverContext` so the
+ * AgentHost can flip them off in tests / lab environments via the
+ * feature flag.
+ */
+import { type LookupAddress } from "node:dns";
+import { type ResolverErrorCode } from "./errors.js";
+import type { ResolvedAsset, ResolverContext, ResourceRef, ResourceResolver } from "../types.js";
+export declare class ResolverError extends Error {
+    readonly code: ResolverErrorCode;
+    readonly meta?: Record<string, unknown> | undefined;
+    constructor(code: ResolverErrorCode, message: string, meta?: Record<string, unknown> | undefined);
+    /** Promtheus-friendly outcome label (subset of error codes). */
+    get outcomeLabel(): string;
+}
+/**
+ * Optional injection hooks for tests. Production passes the real
+ * `globalThis.fetch` and `dns.lookup`.
+ */
+export interface UrlResolverOptions {
+    fetchImpl?: typeof fetch;
+    dnsLookup?: (hostname: string) => Promise<LookupAddress[]>;
+    /**
+     * When set, the platform OS hint is forced to this value, bypassing
+     * `ctx.device.getInfo().os` lookup. Tests use this to drive the
+     * "Android-only media-scan" branch deterministically.
+     */
+    forceDeviceType?: string;
+}
+export declare class UrlResolver implements ResourceResolver {
+    readonly name = "url";
+    private readonly fetchImpl;
+    private readonly dnsLookup;
+    private readonly forceDeviceType?;
+    constructor(opts?: UrlResolverOptions);
+    match(ref: ResourceRef): boolean;
+    resolve(ref: ResourceRef, ctx: ResolverContext): Promise<ResolvedAsset>;
+    private doResolve;
+    private detectPlatform;
+}
+/**
+ * RFC 1918 / RFC 4193 / loopback / link-local / multicast / etc check.
+ * We deliberately keep this exhaustive rather than rely on a third-party
+ * package — the SSRF surface is small and security-critical.
+ *
+ *   IPv4 loopback             — 127.0.0.0/8
+ *   IPv4 RFC1918 private       — 10/8, 172.16/12, 192.168/16
+ *   IPv4 link-local            — 169.254/16
+ *   IPv4 CGNAT                 — 100.64/10
+ *   IPv4 broadcast / multicast — 224/4, 255.255.255.255
+ *   IPv4 0.0.0.0/8             — "this network"
+ *   IPv6 loopback              — ::1
+ *   IPv6 link-local            — fe80::/10
+ *   IPv6 ULA                   — fc00::/7
+ *   IPv6 multicast             — ff00::/8
+ *   IPv6 unspecified           — ::
+ *   IPv4-mapped IPv6           — ::ffff:0:0/96 (mapped to v4 above)
+ */
+export declare function isPrivateOrLoopback(addr: string, family: number): boolean;