Merge branch 'main' into dht

Author: lidel

.github/workflows/build.yml

@@ -1,10 +1,13 @@
-name: Build and Deploy
+# Build workflow - runs for both PRs and main branch pushes
+# This workflow builds the website without access to secrets
+# For PRs: Runs on untrusted fork code safely (using pull_request event, not pull_request_target)
+# For main: Builds and uploads artifacts for deployment
+# Artifacts are passed to the deploy workflow which has access to secrets
+
+name: Build
 
-# Explicitly declare permissions
 permissions:
   contents: read
-  pull-requests: write
-  statuses: write
 
 on:
   push:
@@ -19,16 +22,16 @@ env:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true # Cancel in progress runs if a new run is started
+  cancel-in-progress: true
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
-    outputs:
-      cid: ${{ steps.deploy.outputs.cid }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -42,50 +45,10 @@ jobs:
       - name: Build project
         run: make website
 
-      - name: Upload static files as artifact
-        id: upload-artifact
-        uses: actions/upload-pages-artifact@v3
+      # Upload artifact for deploy workflow
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
         with:
+          name: website-build-${{ github.run_id }}
           path: ${{ env.BUILD_PATH }}
-
-      - uses: ipfs/ipfs-deploy-action@v1
-        name: Deploy to IPFS Mirror Providers
-        id: deploy
-        with:
-          path-to-deploy: ${{ env.BUILD_PATH }}
-          cluster-url: "/dnsaddr/ipfs-websites.collab.ipfscluster.io"
-          cluster-user: ${{ secrets.CLUSTER_USER }}
-          cluster-password: ${{ secrets.CLUSTER_PASSWORD }}
-          storacha-key: ${{ secrets.STORACHA_KEY }}
-          storacha-proof: ${{ secrets.STORACHA_PROOF }}
-          #TODO pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }}
-          github-token: ${{ github.token }}
-
-      # TODO: right now, DNSLink is controlled by Fleek, and we use ipfs/ipfs-deploy-action for PR previews
-      #- name: Update DNSLink
-      #  if: false # TODO github.ref == 'refs/heads/main' # only update DNSLink for main branch
-      #  uses: ipfs/[email protected]
-      #  with:
-      #    cid: ${{ steps.deploy.outputs.cid }}
-      #    dnslink_domain: 'specs.ipfs.tech'
-      #    cf_record_id: ${{ secrets.CF_RECORD_ID }}
-      #    cf_zone_id: ${{ secrets.CF_ZONE_ID }}
-      #    cf_auth_token: ${{ secrets.CF_AUTH_TOKEN }}
-      #    github_token: ${{ github.token }}
-      #    set_github_status: true
-
-
-  gh-pages:
-    runs-on: 'ubuntu-latest'
-    needs: build-and-deploy
-    if: github.ref == 'refs/heads/main' # only deploy to gh-pages for main branch
-    permissions:
-      pages: write      # to deploy to Pages
-      id-token: write   # to verify the deployment originates from an appropriate source
-    environment:
-      name: 'github-pages'
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          retention-days: 1

.github/workflows/deploy.yml

@@ -0,0 +1,91 @@
+# Deploy workflow - triggered by workflow_run after successful build
+# This workflow has access to secrets but never executes untrusted code
+# It only downloads and deploys pre-built artifacts from the build workflow
+# Security: Fork code cannot access secrets as it only runs in build workflow
+# Deploys to IPFS for all branches and GitHub Pages for main branch only
+
+name: Deploy
+
+# Explicitly declare permissions
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+
+on:
+  workflow_run:
+    workflows: ["Build"]
+    types: [completed]
+
+env:
+  BUILD_PATH: 'website-build'
+
+jobs:
+  deploy-ipfs:
+    if: github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    outputs:
+      cid: ${{ steps.deploy.outputs.cid }}
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: website-build-${{ github.event.workflow_run.id }}
+          path: ${{ env.BUILD_PATH }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Deploy to IPFS Mirror Providers
+        uses: ipshipyard/ipfs-deploy-action@v1
+        id: deploy
+        with:
+          path-to-deploy: ${{ env.BUILD_PATH }}
+          cluster-url: "/dnsaddr/ipfs-websites.collab.ipfscluster.io"
+          cluster-user: ${{ secrets.CLUSTER_USER }}
+          cluster-password: ${{ secrets.CLUSTER_PASSWORD }}
+          storacha-key: ${{ secrets.STORACHA_KEY }}
+          storacha-proof: ${{ secrets.STORACHA_PROOF }}
+          #TODO pinata-jwt-token: ${{ secrets.PINATA_JWT_TOKEN }}
+          github-token: ${{ github.token }}
+
+      # TODO: right now, DNSLink is controlled by Fleek, and we use ipfs/ipfs-deploy-action for PR previews
+      #- name: Update DNSLink
+      #  if: github.event.workflow_run.head_branch == 'main'
+      #  uses: ipfs/[email protected]
+      #  with:
+      #    cid: ${{ steps.deploy.outputs.cid }}
+      #    dnslink_domain: 'specs.ipfs.tech'
+      #    cf_record_id: ${{ secrets.CF_RECORD_ID }}
+      #    cf_zone_id: ${{ secrets.CF_ZONE_ID }}
+      #    cf_auth_token: ${{ secrets.CF_AUTH_TOKEN }}
+      #    github_token: ${{ github.token }}
+      #    set_github_status: true
+
+  deploy-gh-pages:
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: website-build-${{ github.event.workflow_run.id }}
+          path: website-build
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website-build
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/generated-pr.yml

@@ -0,0 +1,14 @@
+name: Close Generated PRs
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    uses: ipdxco/unified-github-workflows/.github/workflows/reusable-generated-pr.yml@v1

.github/workflows/stale.yml

@@ -1,13 +1,14 @@
-name: Close and mark stale issue
+name: Close Stale Issues
 
 on:
   schedule:
     - cron: '0 0 * * *'
+  workflow_dispatch:
 
 permissions:
   issues: write
   pull-requests: write
 
 jobs:
   stale:
-    uses: pl-strflt/.github/.github/workflows/reusable-stale-issue.yml@v0.3
+    uses: ipdxco/unified-github-workflows/.github/workflows/reusable-stale-issue.yml@v1

.markdownlint.json

@@ -8,5 +8,6 @@
   "blanks-around-lists": false,
   "single-trailing-newline": false,
   "link-fragments": false,
-  "line-length": false
+  "line-length": false,
+  "blanks-around-fences": false
 }

ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) IPFS Architecture Overview
 
+> [!NOTE]
+> This document contains historical notes about IPFS architecture from ~2015. For current specifications, please refer to https://specs.ipfs.tech/
 
 **Authors(s)**:
 - [Juan Benet](https://github.com/jbenet)

DWEB_ADDRESSING.md

@@ -1,5 +1,8 @@
 # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Addressing on the Decentralized Web
 
+> [!NOTE]
+> This is an incomplete work-in-progress document from the early days of IPFS. For current addressing specifications, please refer to https://specs.ipfs.tech/
+
 **Authors(s)**:
 - [Lars Gierth](mailto:[email protected])
 

IMPORTERS_EXPORTERS.md

@@ -1,5 +1,8 @@
 # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) Data Importers & Exporters
 
+> [!NOTE]
+> This is a work-in-progress specification from the early days of IPFS. For current UnixFS and data import specifications, please refer to https://specs.ipfs.tech/unixfs/
+
 **Authors(s)**:
 - David Dias
 - Juan Benet
@@ -43,7 +46,7 @@ Essentially, data importing is divided into two parts:
 - Splitters - The chunking algorithms applied to each file, these can be:
   - fixed size chunking (also known as dumb chunking)
   - rabin fingerprinting
-  - dedicated format chunking, these require knowledge of the format and typically only work with certain time of files (e.g. video, audio, images, etc)
+  - dedicated format chunking, these require knowledge of the format and typically only work with certain type of files (e.g. video, audio, images, etc)
   - special data structures chunking, formats like, tar, pdf, doc, container and/org vm images fall into this category
 
 ### Goals

KEYCHAIN.md

@@ -1,5 +1,8 @@
 # ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) The Keychain
 
+> [!NOTE]
+> This is a work-in-progress specification from the early days of IPFS that was never completed. It remains here for historical reference.
+
 **Authors(s)**:
 - [Juan Benet](github.com/jbenet)
 

README.md

@@ -35,7 +35,7 @@ The specs contained in this and related repositories are:
 
 - **IPFS Protocol:**
   - [IPFS Guide](https://docs.ipfs.tech/) - to start your IPFS journey
-  - [Protocol Architecture Overview](./ARCHITECTURE.md) - the top-level spec and the stack
+  - [Protocol Architecture Overview (Historical Notes from ~2015)](./ARCHITECTURE.md) - the top-level spec and the stack
 - **User Interface (aka Public APIs):**
   - [HTTP Gateways](https://specs.ipfs.tech/http-gateways/) - implementation agnostic interfaces for accessing content-addressed data over HTTP
   - [Routing V1](https://specs.ipfs.tech/routing/http-routing-v1/) - implementation agnostic interfaces for content/peer/IPNS routing over HTTP
@@ -45,31 +45,31 @@ The specs contained in this and related repositories are:
   - [IPLD](https://ipld.io/specs/) - InterPlanetary Linked Data.
     - [DAG-CBOR](https://ipld.io/docs/codecs/known/dag-cbor/) -  binary format, supporting the complete IPLD Data Model, with excellent performance, and suitable for any job.
     - [DAG-JSON](https://ipld.io/docs/codecs/known/dag-json/) - human-readable format, supporting almost the complete IPLD Data Model, and very convenient for interoperability, development, and debugging.
-    - [DAG-PB](https://ipld.io/docs/codecs/known/dag-pb/) - a binary format for specific limited structures of data, which is highly used in IPFS and [UnixFS](./UNIXFS.md).
+    - [DAG-PB](https://ipld.io/docs/codecs/known/dag-pb/) - a binary format for specific limited structures of data, which is highly used in IPFS and [UnixFS](https://specs.ipfs.tech/unixfs/).
     - [CAR](https://ipld.io/specs/transport/car/) - transport format used to store content addressable objects in the form of IPLD block data as a sequence of bytes; typically as an [application/vnd.ipld.car](https://www.iana.org/assignments/media-types/application/vnd.ipld.car) file with a `.car` extension
   - Self Describing Formats ([multiformats](http://github.com/multiformats/multiformats)):
     - [multihash](https://github.com/multiformats/multihash) - self-describing hash digest format.
     - [multiaddr](https://github.com/multiformats/multiaddr) - self-describing addressing format.
     - [multicodec](https://github.com/multiformats/multicodec) - self-describing protocol/encoding streams (note: a file is a stream).
     - [multistream](https://github.com/multiformats/multistream) - multistream is a format -- or simple protocol -- for disambiguating, and layering streams. It is extremely simple.
 - **Files and Directories:**
-  - [UnixFS](./UNIXFS.md)
+  - [UnixFS](https://specs.ipfs.tech/unixfs/)
   - Related userland concepts (external docs):
     - [MFS, Mutable File System, or the Files API](https://docs.ipfs.tech/concepts/file-systems/#mutable-file-system-mfs)
 - **Storage Layer:**
   - [Pinning Service API](https://ipfs.github.io/pinning-services-api-spec/)
-  - [Repo](./REPO.md) - IPFS node local repository spec
-    - [FileSystem Repo](./REPO_FS.md) - IPFS node local repository spec
+  - [Repo](https://github.com/ipfs/kubo/blob/master/docs/specifications/repository.md) - Kubo-specific local repository implementation details
+    - [FileSystem Repo](https://github.com/ipfs/kubo/blob/master/docs/specifications/repository_fs.md) - Kubo-specific filesystem repository implementation
 - **Block Exchanges:**
-  - [Bitswap](./BITSWAP.md) - BitTorrent-inspired exchange
+  - [Bitswap](https://specs.ipfs.tech/bitswap-protocol/) - BitTorrent-inspired exchange
 - **Key Management:**
-  - [KeyStore](./KEYSTORE.md) - Key management on IPFS
+  - [KeyStore](https://github.com/ipfs/kubo/blob/master/docs/specifications/keystore.md) - Kubo-specific key management implementation
   - [KeyChain](./KEYCHAIN.md) - Distribution of cryptographic Artifacts
 - **Networking layer:**
   - [libp2p](https://github.com/libp2p/specs) - libp2p is a modular and extensible network stack, built and use by IPFS, but that it can be reused as a standalone project. Covers:
 - **Records, Naming and Record Systems:**
   - [IPNS](https://specs.ipfs.tech/ipns/) - InterPlanetary Naming System
-    - [IPNS Record Creation and Verification](https://specs.ipfs.tech/ipns/ipns-pubsub-router/)
+    - [IPNS Record Creation and Verification](https://specs.ipfs.tech/ipns/ipns-record/)
     - [IPNS over PubSub](https://specs.ipfs.tech/ipns/ipns-pubsub-router/)
   - [DNSLink](https://dnslink.dev) - mapping DNS names to IPFS content paths
   - [DNSAddr](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md) - mapping DNS names to libp2p multiaddrs