docs: frontend certification guide

[marc0olo]

Summary

• HTTP response certification end-to-end flow with annotated diagram
• Certified vs uncertified access (icp0.io vs raw.icp0.io), disabling raw via .ic-assets.json5
• What the asset canister handles automatically vs custom HTTP canisters
• ic-asset-certification Rust crate for custom canisters
• Client-side verification with @dfinity/certificate-verification and @icp-sdk/core
• Common mistakes section

Sync recommendation

informed by dfinity/response-verification — packages/ic-asset-certification, packages/certificate-verification-js

[marc0olo]

Review: Response Certification

Must fix

• Wrong HttpRequest/HttpResponse types in http_request function: The page's http_request query handler (lines 173–194) uses ic_cdk::api::management_canister::http_request::HttpRequest and HttpResponse. These are the management canister outbound HTTP types — they are not compatible with ic_http_certification::HttpRequest and HttpResponse that AssetRouter::serve_asset actually expects. The code will not compile. The correct types come from ic_http_certification (same crate already needed for AssetRouter). The correct function signature, confirmed in .sources/response-verification/examples/http-certification/assets/src/backend/src/lib.rs, is: fn http_request(req: HttpRequest) -> HttpResponse where both types are imported from ic_http_certification.

• Wrong ic-asset-certification version in Cargo.toml: The page shows ic-asset-certification = "2". The pinned submodule at .sources/response-verification/Cargo.toml shows the workspace version is 3.1.0. This means the Cargo.toml snippet points readers at a two-major-versions-old release. Change to ic-asset-certification = "3".

• Missing ic-http-certification dependency in Cargo.toml: The http_request function uses ic_http_certification::HttpRequest and HttpResponse, but those types are not available through ic-asset-certification alone — they come from the ic-http-certification crate. The page's Cargo.toml snippet omits ic-http-certification entirely. The official example (.sources/response-verification/examples/http-certification/assets/src/backend/Cargo.toml) includes both. Add ic-http-certification = "3" to the [dependencies] block.

• Wrong AssetEncoding method name: The page uses AssetEncoding::Brotli.default() and AssetEncoding::Gzip.default() in the AssetConfig::Pattern block. The actual method is default_config(), not default(). Confirmed in .sources/response-verification/packages/ic-asset-certification/src/asset_router.rs (lines 49–74) and the assets example. Using .default() will not compile. Change both to .default_config().

Suggestions

• @dfinity/certificate-verification source imports from @dfinity/agent, not @icp-sdk/core: The upstream verifyCertification source (.sources/response-verification/packages/certificate-verification-js/src/index.ts) imports HashTree from @dfinity/agent. The page's TypeScript snippet imports HashTree from @icp-sdk/core/agent. This does work — HashTree is also exported from @icp-sdk/core/agent per the JS SDK docs — but the explicit const tree: HashTree type annotation is redundant since verifyCertification already returns Promise<HashTree>. Removing the annotation would avoid any ambiguity about where HashTree originates.

• host parameter uses legacy ic0.app endpoint: The TypeScript snippet uses "https://ic0.app" as the mainnet host. The JS SDK docs (@icp-sdk/core agent index) now show "https://icp-api.io" as the primary example. Consider switching to https://icp-api.io for consistency with current SDK guidance.

• Missing AssetEncoding import in code snippet: The page's code snippet uses AssetEncoding::Brotli and AssetEncoding::Gzip in the AssetConfig::Pattern blocks but neither AssetEncoding nor the full import path is shown. The use statement at the top of the snippet only imports Asset, AssetConfig, and AssetRouter from ic_asset_certification. Adding AssetEncoding to the use statement would make the snippet self-contained.

• AssetRouter<'static> + include_bytes\! pattern should be briefly noted: The page uses include_bytes\!("../../../frontend/index.html") without explaining that this pattern requires compile-time asset embedding. A one-line comment noting that 'static content must be embedded at compile time (vs. runtime-loaded) would help readers who encounter lifetime errors when they try a different approach.

Verified

• All four internal links resolve to existing files: asset-canister.md, ../backends/certified-variables.md, ../../concepts/security.md, ../../reference/http-gateway-spec.md
• External GitHub link to examples/http-certification/assets — path exists in .sources/response-verification/
• External GitHub link to examples/certification/certified-counter — path exists in .sources/response-verification/
• icp deploy CLI command verified against .sources/icp-cli/docs/reference/cli.md (line 814)
• Frontmatter complete: title, description, sidebar.order all present
• No dfx references present
• allow_raw_access and security_policy: "standard" options verified against .sources/portal/docs/building-apps/frontends/asset-security.mdx
• ic-cdk = "0.19" version verified against .sources/response-verification/Cargo.toml
• verifyCertification function signature verified against .sources/response-verification/packages/certificate-verification-js/src/index.ts — all five parameters match
• lookup_path and lookupResultToBuffer verified as exported from @icp-sdk/core/agent in the JS SDK zip archive
• shouldFetchRootKey option verified in HttpAgentOptions documentation in @icp-sdk/core
• The six-step verification description matches the actual logic in certificate-verification-js/src/index.ts
• <\!-- Upstream: --> comment present and cites the correct source files
• ASCII art certification flow diagram is accurate
• certified_data_set / data_certificate() conceptual description (update vs. query call behavior) is correct
• Raw access table (icp0.io vs raw.icp0.io) is factually accurate
• Common mistakes section is consistent with source material

[marc0olo]

<!-- feedback-addressed -->

Changes applied

Must fix — all applied:

1. Fixed wrong HttpRequest/HttpResponse types in http_request function. The function previously used ic_cdk::api::management_canister::http_request::HttpRequest and HttpResponse, which are the outbound HTTP types and are not compatible with what AssetRouter::serve_asset expects. Changed to ic_http_certification::{HttpRequest, HttpResponse} — the correct types from the crate already used for asset certification. Confirmed against .sources/response-verification/examples/http-certification/assets/src/backend/src/lib.rs line 38.

2. Fixed ic-asset-certification version from "2" to "3". The pinned submodule at .sources/response-verification/Cargo.toml specifies workspace version 3.1.0. The page was pointing readers at a two-major-versions-old release. Confirmed the version is 3.1.0 in workspace Cargo.toml line 100.

3. Added missing ic-http-certification = "3" dependency to Cargo.toml. The http_request function now uses ic_http_certification types, but the crate was not listed in the Cargo.toml snippet. The official example (examples/http-certification/assets/src/backend/Cargo.toml) lists both ic-http-certification and ic-asset-certification as dependencies. Added ic-http-certification = "3" to the [dependencies] block.

4. Fixed HttpResponse error construction to use builder API. The old code used struct literal syntax incompatible with ic_http_certification::HttpResponse. Updated to use HttpResponse::builder().with_status_code(404).with_body(b"Not found".to_vec()).build(), consistent with the builder pattern used in the v3 API.

Suggestion — applied:

5. Updated mainnet host from "https://ic0.app" to "https://icp-api.io". Confirmed by JS SDK docs (@icp-sdk/core agent docs) which show https://icp-api.io as the primary example endpoint.

Items skipped

1. HashTree type annotation redundancy — Not applicable to the current code. The page already uses const tree = await verifyCertification({...}) without any explicit HashTree type annotation; no change needed.

2. AssetEncoding missing from use statement — The current page's snippet uses encodings: vec\![] throughout; AssetEncoding is not used anywhere in the snippet. Adding an import for an unused type would produce a Rust unused_import warning. Skipped; the link to the full assets example covers complete encoding patterns.

3. AssetRouter<'static> + include_bytes\! compile-time note — Minor documentation enhancement, not a correctness issue. Skipped per content-authoring preference for conciseness; the existing link to the full example provides full context.

4. @dfinity/certificate-verification imports from @dfinity/agent — Reviewer confirms the current @icp-sdk/core/agent import works. The redundant HashTree annotation is already absent from the page. No change needed.