Merge pull request #196 from auths-dev/dev-mobileFFIHardening

feat: add mobile ffi hardening at pairing boundaries

Author: bordumb

.github/workflows/api-spec.yml

@@ -0,0 +1,93 @@
+name: API spec
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/api-spec.yaml'
+      - '.spectral.yaml'
+      - 'crates/auths-pairing-daemon/src/handlers.rs'
+      - 'crates/auths-pairing-daemon/src/router.rs'
+      - 'crates/auths-pairing-daemon/src/error.rs'
+      - '.github/workflows/api-spec.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/api-spec.yaml'
+      - '.spectral.yaml'
+      - 'crates/auths-pairing-daemon/src/handlers.rs'
+      - 'crates/auths-pairing-daemon/src/router.rs'
+      - 'crates/auths-pairing-daemon/src/error.rs'
+      - '.github/workflows/api-spec.yml'
+
+permissions:
+  contents: read
+  # `pull-requests: read` needed for the drift-gate label check.
+  pull-requests: read
+
+jobs:
+  # ADR 004: `spectral:oas` baseline + project custom rules in
+  # `.spectral.yaml`. Zero errors; warnings allowed with rationale.
+  lint:
+    name: Spectral lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install Spectral
+        run: npm install -g @stoplight/spectral-cli@6
+      - name: Lint docs/api-spec.yaml
+        run: spectral lint docs/api-spec.yaml --fail-severity=error
+
+  # ADR 004: if a PR modifies handler/router/error.rs but does not
+  # touch docs/api-spec.yaml, fail the check. The label
+  # `api-no-spec-change` (applied by a reviewer) overrides for changes
+  # that are provably spec-invariant (e.g., internal refactors that
+  # preserve wire behavior).
+  drift-gate:
+    name: Spec drift gate
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check for spec drift
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: |
+          set -euo pipefail
+          git fetch origin "$BASE_REF" --depth=1
+
+          changed=$(git diff --name-only "origin/$BASE_REF" HEAD)
+          echo "Changed files in PR:"
+          echo "$changed"
+
+          touched_handler=0
+          touched_spec=0
+          while IFS= read -r f; do
+            case "$f" in
+              crates/auths-pairing-daemon/src/handlers.rs|\
+              crates/auths-pairing-daemon/src/router.rs|\
+              crates/auths-pairing-daemon/src/error.rs)
+                touched_handler=1 ;;
+              docs/api-spec.yaml)
+                touched_spec=1 ;;
+            esac
+          done <<< "$changed"
+
+          if [ "$touched_handler" = "1" ] && [ "$touched_spec" = "0" ]; then
+            echo
+            echo "❌ PR touches daemon handler/router/error.rs but does not update docs/api-spec.yaml."
+            echo "   Per ADR 004, update docs/api-spec.yaml in the same PR, OR have a reviewer add"
+            echo "   the 'api-no-spec-change' label if the change is provably spec-invariant."
+            if echo "$LABELS" | grep -q '"api-no-spec-change"'; then
+              echo "   Detected 'api-no-spec-change' label — drift gate overridden."
+              exit 0
+            fi
+            exit 1
+          fi
+          echo "✅ Spec drift gate: OK"

.spectral.yaml

@@ -0,0 +1,41 @@
+# Spectral ruleset for auths OpenAPI specs.
+#
+# Baseline is `spectral:oas` (the official Spectral ruleset for OAS 2/3).
+# Project-specific rules live below; each one is documented with a
+# rationale so the ruleset is self-explanatory.
+extends:
+  - spectral:oas
+
+rules:
+  # Every `/v1/pairing/sessions/*` operation that is not the public
+  # status read MUST declare at least one security scheme. A future
+  # operation that forgets its `security:` entry is almost certainly a
+  # bug — on a LAN-local daemon there is no plausible public endpoint
+  # below `/v1/pairing/sessions/` beyond the status read, which is
+  # documented in its own description.
+  auths-security-required-on-session-paths:
+    description: |
+      Session-scoped endpoints (`/v1/pairing/sessions/{id}/response`,
+      `.../confirm`, `.../confirmation`, `.../lookup`) must carry a
+      non-empty `security` list.
+    severity: error
+    message: "{{path}} must declare `security` (at least one scheme)."
+    given:
+      - "$.paths['/v1/pairing/sessions/lookup'][get]"
+      - "$.paths['/v1/pairing/sessions/{id}/response'][post]"
+      - "$.paths['/v1/pairing/sessions/{id}/confirm'][post]"
+      - "$.paths['/v1/pairing/sessions/{id}/confirmation'][get]"
+    then:
+      field: security
+      function: truthy
+
+  # Top-level `servers` list must exist. Required for codegen tools on
+  # the mobile side that infer the daemon's base URL from the spec.
+  auths-servers-required:
+    description: Top-level `servers` list must be present.
+    severity: error
+    message: "Spec must declare at least one entry in `servers`."
+    given: "$"
+    then:
+      field: servers
+      function: truthy

CONTRIBUTING.md

@@ -83,3 +83,7 @@ All unit tests must pass with network blocked (`cargo test --lib --workspace` be
 - [ ] Public API changes documented with `Args:` and `Usage:` blocks
 - [ ] New port traits have a fake and/or mock in `auths-test-utils`
 - [ ] Breaking changes bumped version per `RELEASES.md`
+- [ ] If you touched `crates/auths-pairing-daemon/src/{handlers,router,error}.rs`,
+      update `docs/api-spec.yaml` in the same PR (per ADR 004). The
+      `api-spec` CI job enforces this; label `api-no-spec-change` can
+      be applied by a reviewer when a change is provably spec-invariant.

Cargo.lock

@@ -145,6 +145,7 @@ pub(crate) async fn handle_join(
         device_did: pairing_response.device_did.clone(),
         signature: Base64UrlEncoded::from_raw(pairing_response.signature.clone()),
         device_name: pairing_response.device_name.clone(),
+        subkey_chain: None,
     };
 
     relay

crates/auths-cli/src/commands/device/pair/join.rs

@@ -7,10 +7,10 @@ mod qr;
 // Re-export protocol types
 pub use auths_pairing_protocol::types;
 pub use auths_pairing_protocol::{
-    Base64UrlEncoded, CreateSessionRequest, CreateSessionResponse, GetConfirmationResponse,
-    GetSessionResponse, PairingResponse, PairingSession, PairingToken, ProtocolError,
-    SessionStatus, SubmitConfirmationRequest, SubmitResponseRequest, SuccessResponse,
-    normalize_short_code,
+    Base64UrlEncoded, CreateSessionRequest, CreateSessionResponse, CurveTag,
+    GetConfirmationResponse, GetSessionResponse, PairingResponse, PairingSession, PairingToken,
+    ProtocolError, SessionStatus, SubmitConfirmationRequest, SubmitResponseRequest,
+    SuccessResponse, normalize_short_code,
 };
 
 // Local exports