Merge branch 'main' into docs/security-port

Author: raymondk

.github/CODEOWNERS

@@ -1,11 +1,21 @@
 # All files are owned by the DX team.
 # At least one DX team member must approve every PR before it can be merged.
-# DX team members are also configured as bypass actors in the branch ruleset
-# and can merge their own PRs without a separate review.
 * @dfinity/dx
 
+
+# Interface specification — additional required reviewers for spec files and attachments.
+# GitHub CODEOWNERS: last matching rule wins, so these override the wildcard above.
+docs/references/ic-interface-spec/* @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+docs/references/http-gateway-protocol-spec.md @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+docs/references/management-canister.md @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+docs/references/execution-errors.md @dfinity/team-dsm @dfinity/dx
+public/references/ic.did @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+public/references/certificates.cddl @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+public/references/requests.cddl @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+public/references/http-gateway.did @dfinity/interface-spec @dfinity/team-dsm @dfinity/consensus @dfinity/dx
+
 # Security — product-security team must approve changes to security best practices
 docs/guides/security/ @dfinity/product-security @dfinity/dx
 docs/concepts/security.md @dfinity/product-security @dfinity/dx
 docs/references/message-execution-properties.md @dfinity/product-security @dfinity/dx
-docs/guides/canister-calls/idempotency.md @dfinity/product-security @dfinity/dx
+docs/guides/canister-calls/idempotency.md @dfinity/product-security @dfinity/dx

.github/workflows/interface-spec-slack.yml

@@ -0,0 +1,43 @@
+name: Interface Specification PR Slack Notification
+
+on:
+  pull_request:
+    types: [opened, ready_for_review]
+    paths:
+      - .github/workflows/interface-spec.yml
+      - .github/workflows/interface-spec-tag.yml
+      - .github/workflows/interface-spec-slack.yml
+      - docs/references/ic-interface-spec/**
+      - docs/references/http-gateway-protocol-spec.md
+      - public/references/certificates.cddl
+      - public/references/requests.cddl
+      - public/references/http-gateway.did
+      - public/references/ic.did
+
+jobs:
+  notify-slack:
+    name: Notify Slack
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Sanitize PR title
+        id: sanitize
+        env:
+          RAW_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          ESCAPED_TITLE=$(echo "$RAW_TITLE" \
+            | sed 's/&/\&/g' \
+            | sed 's/</\&lt;/g' \
+            | sed 's/>/\&gt;/g')
+          echo "safe_title=$ESCAPED_TITLE" >> "$GITHUB_OUTPUT"
+
+      - name: Post to Slack
+        uses: slackapi/slack-github-action@91efab103c0de0a537f72a35f6b8cda0ee76bf0a # v2.1.1
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_API_TOKEN }}
+          payload: |
+            channel: interface-spec
+            text: ":github: `${{ github.repository }}` <${{ github.event.pull_request.html_url }}|${{ steps.sanitize.outputs.safe_title }}>"

.github/workflows/interface-spec-tag.yml

@@ -0,0 +1,40 @@
+name: Interface Specification Tag
+
+on:
+  pull_request_target:
+    paths:
+      - .github/workflows/interface-spec.yml
+      - .github/workflows/interface-spec-tag.yml
+      - .github/workflows/interface-spec-slack.yml
+      - docs/references/ic-interface-spec/**
+      - docs/references/http-gateway-protocol-spec.md
+      - public/references/certificates.cddl
+      - public/references/requests.cddl
+      - public/references/http-gateway.did
+      - public/references/ic.did
+
+jobs:
+  interface-spec-tag:
+    name: Tag PR with interface-spec
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Create label if missing
+        run: |
+          gh label create interface-spec \
+            --color 0075ca \
+            --description "Changes to the IC interface specification" \
+            --repo ${{ github.repository }} \
+            --force
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tag PR with interface-spec
+        run: |
+          gh pr edit ${{ github.event.pull_request.number }} \
+            --add-label interface-spec \
+            --repo ${{ github.repository }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/interface-spec.yml

@@ -0,0 +1,38 @@
+name: Interface Specification
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/interface-spec.yml
+      - docs/references/ic-interface-spec/**
+      - docs/references/http-gateway-protocol-spec.md
+      - public/references/certificates.cddl
+      - public/references/requests.cddl
+      - public/references/http-gateway.did
+      - public/references/ic.did
+  push:
+    branches:
+      - main
+
+jobs:
+  cddl:
+    name: Check cddl files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Check cddl files
+        run: |
+          docker run --rm -v $PWD/public/references:/workdir ghcr.io/anweiss/cddl-cli:0.9.1 compile-cddl --cddl /workdir/certificates.cddl
+          docker run --rm -v $PWD/public/references:/workdir ghcr.io/anweiss/cddl-cli:0.9.1 compile-cddl --cddl /workdir/requests.cddl
+
+  candid:
+    name: Check candid files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Check candid files
+        run: |
+          curl -L https://github.com/dfinity/candid/releases/download/2023-07-25/didc-linux64 -o didc
+          chmod +x didc
+          ./didc check public/references/http-gateway.did
+          ./didc check public/references/ic.did

astro.config.mjs

@@ -7,6 +7,7 @@ import remarkIcpCliVersion from "./plugins/remark-icp-cli-version.mjs";
 import remarkSnippet from "./plugins/remark-snippet.mjs";
 import remarkHeadingId from "./plugins/remark-heading-id.mjs";
 import remarkPlantUML from "./plugins/remark-plantuml.mjs";
+import remarkIncludeFile from "./plugins/remark-include-file.mjs";
 import agentDocs from "./plugins/astro-agent-docs.mjs";
 import { sidebar } from "./sidebar.mjs";
 import { TITLE, DESCRIPTION, PUBLISHER, OG_ALT } from "./src/branding.mjs";
@@ -18,7 +19,7 @@ export default defineConfig({
     // Rehype plugins work with Starlight (remark plugins don't — Starlight overrides them).
     // See: https://github.com/dfinity/icp-cli/issues/423
     rehypePlugins: [rehypeRewriteLinks, rehypeExternalLinks],
-    remarkPlugins: [remarkHeadingId, remarkSnippet, remarkIcpCliVersion, remarkPlantUML],
+    remarkPlugins: [remarkHeadingId, remarkSnippet, remarkIcpCliVersion, remarkPlantUML, remarkIncludeFile],
   },
   integrations: [
     starlight({

docs/guides/frontends/certification.md

@@ -318,6 +318,6 @@ For the full working example including a backend canister, see the [certified-co
 - [Asset canister](asset-canister.md): deploy and configure the standard asset canister with automatic certification
 - [Certified variables](../backends/certified-variables.md): certify Candid query responses from backend canisters
 - [Security concepts](../../concepts/security.md): why query integrity matters
-- [HTTP Gateway specification](../../references/http-gateway-spec.md): how boundary nodes verify responses
+- [HTTP Gateway specification](../../references/http-gateway-protocol-spec.md): how boundary nodes verify responses
 
 <!-- Upstream: informed by dfinity/response-verification — packages/ic-asset-certification/README.md, packages/ic-http-certification/README.md, packages/certificate-verification-js/README.md, packages/certificate-verification-js/src/index.ts, examples/certification/certified-counter; dfinity/portal — docs/building-apps/frontends/asset-security.mdx; dfinity/icskills — skills/certified-variables/SKILL.md, skills/asset-canister/SKILL.md -->

docs/references/http-gateway-spec.md …references/http-gateway-protocol-spec.mddocs/references/http-gateway-spec.md renamed to docs/references/http-gateway-protocol-spec.md docs/references/http-gateway-spec.md renamed to docs/references/http-gateway-protocol-spec.md

@@ -434,7 +434,7 @@ service : {
 }
 ```
 
-You can also [download the file](/references/_attachments/http-gateway.did).
+You can also [download the file](/references/http-gateway.did).
 
 Not all of this interface is required. The following sections detail what can be optionally omitted depending on the requirements of the canister in question.
 

docs/references/ic-interface-spec/certification.md

@@ -179,7 +179,7 @@ Delegations are *scoped*, i.e., they indicate which set of canister principals t
 
 ### Encoding of certificates {#certification-encoding}
 
-The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/_attachments/certificates.cddl).
+The binary encoding of a certificate is a CBOR (see [CBOR](./index.md#cbor)) value according to the following CDDL (see [CDDL](./index.md#cddl)). You can also [download the file](/references/certificates.cddl).
 
 The values in the [The system state tree](./index.md#state-tree) are encoded to blobs as follows:
 
@@ -251,6 +251,6 @@ In the pruned tree, the `lookup_path` function behaves as follows:
 
 ## The HTTP Gateway protocol {#http-gateway}
 
-The HTTP Gateway Protocol has been moved into its own [specification](../http-gateway-spec.md).
+The HTTP Gateway Protocol has been moved into its own [specification](../http-gateway-protocol-spec.md).
 
 <!-- Upstream: sync from dfinity/portal — docs/references/ic-interface-spec.md -->

docs/references/ic-interface-spec/https-interface.md

@@ -735,7 +735,7 @@ A typical request would be (written in [CBOR diagnostic notation](https://www.rf
 
 ### CDDL description of requests and responses {#api-cddl}
 
-This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/_attachments/requests.cddl) and see [CDDL](./index.md#cddl) for more information.
+This section summarizes the format of the CBOR data passed to and from the entry points described above. You can also [download the file](/references/requests.cddl) and see [CDDL](./index.md#cddl) for more information.
 
 ### Ordering guarantees
 

docs/references/ic-interface-spec/management-canister.md

@@ -22,7 +22,10 @@ It is possible to use the management canister via external requests (a.k.a. ingr
 
 ### Interface overview {#ic-candid}
 
-The [interface description](/reference/ic.did), in [Candid syntax](../candid-spec.md), describes the available functionality.
+The interface description below, in [Candid syntax](../candid-spec.md), describes the available functionality. You can also [download the file](/references/ic.did).
+
+```candid file=<rootDir>/public/references/ic.did
+```
 
 The binary encoding of arguments and results are as per Candid specification.