Strycher
3 days ago
committed by
GitHub
commit
cbd4550ca4
@ -0,0 +1,34 @@
|
||||
#!/usr/bin/env bash
|
||||
# Decides whether an altool run worked, from its exit code AND its output
|
||||
# (#1040). altool has exited 0 with an error in its output, so a clean exit alone
|
||||
# proves nothing, and nothing short of its success line counts as success.
|
||||
#
|
||||
# usage: ios-altool-check.sh <validate|upload> <exit code> <output file>
|
||||
set -eu
|
||||
|
||||
mode="${1:?mode}"
|
||||
code="${2:?exit code}"
|
||||
output="${3:?output file}"
|
||||
|
||||
case "${mode}" in
|
||||
validate) success='VALIDATION SUCCEEDED|No errors validating' ;;
|
||||
upload) success='UPLOAD SUCCEEDED|No errors uploading' ;;
|
||||
*)
|
||||
echo "::error::Unknown altool mode '${mode}'."
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
if [ "${code}" != "0" ]; then
|
||||
echo "::error::altool ${mode} exited ${code}."
|
||||
exit 1
|
||||
fi
|
||||
if grep -Eq '\*\*\* Error|ERROR:|FAILED' "${output}"; then
|
||||
echo "::error::altool ${mode} exited 0, but its output contains an error."
|
||||
exit 1
|
||||
fi
|
||||
if ! grep -Eq "${success}" "${output}"; then
|
||||
echo "::error::altool ${mode} exited 0, but its output has no success line."
|
||||
exit 1
|
||||
fi
|
||||
echo "altool ${mode} succeeded."
|
||||
@ -0,0 +1,25 @@
|
||||
#!/usr/bin/env bash
|
||||
# Fails unless a built Runner.app holds the native-asset libraries (#1037).
|
||||
# An iOS build can compile with them missing, and the app then fails only at
|
||||
# runtime, when it opens storage or loads translation.
|
||||
set -eu
|
||||
|
||||
app="${1:?usage: ios-assert-frameworks.sh <path to Runner.app>}"
|
||||
frameworks="${app}/Frameworks"
|
||||
|
||||
if [ ! -d "${frameworks}" ]; then
|
||||
echo "::error::No Frameworks folder at ${frameworks}."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Frameworks in ${app}:"
|
||||
ls -1 "${frameworks}"
|
||||
|
||||
missing=0
|
||||
for lib in sqlite3 llama; do
|
||||
if ! ls -1 "${frameworks}" | grep -qi "${lib}"; then
|
||||
echo "::error::No ${lib} framework in ${frameworks}."
|
||||
missing=1
|
||||
fi
|
||||
done
|
||||
exit "${missing}"
|
||||
@ -0,0 +1,69 @@
|
||||
"""Polls Apple's notary service for one submission until it settles or a deadline passes.
|
||||
|
||||
Usage: notary-wait.py <submission-id> <deadline-minutes>
|
||||
Env: P8 (path to the App Store Connect .p8), NOTARY_KEY_ID, NOTARY_ISSUER_ID
|
||||
|
||||
Exit 0 only on Accepted. Invalid/Rejected print Apple's log and exit 1. Still
|
||||
In Progress at the deadline exits 1 with how to resume: the submission keeps
|
||||
going at Apple, and "Re-run failed jobs" polls the same id again (#1109).
|
||||
"""
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
|
||||
import jwt
|
||||
|
||||
API = "https://appstoreconnect.apple.com/notary/v2/submissions/"
|
||||
POLL_SECONDS = 60
|
||||
|
||||
submission_id = sys.argv[1]
|
||||
deadline = time.time() + int(sys.argv[2]) * 60
|
||||
with open(os.environ["P8"], encoding="utf-8") as fh:
|
||||
private_key = fh.read()
|
||||
|
||||
|
||||
def get(url, auth=True):
|
||||
headers = {}
|
||||
if auth:
|
||||
now = int(time.time())
|
||||
token = jwt.encode(
|
||||
{"iss": os.environ["NOTARY_ISSUER_ID"], "iat": now, "exp": now + 600, "aud": "appstoreconnect-v1"},
|
||||
private_key, algorithm="ES256", headers={"kid": os.environ["NOTARY_KEY_ID"], "typ": "JWT"},
|
||||
)
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=30) as response:
|
||||
return json.load(response)
|
||||
|
||||
|
||||
while True:
|
||||
try:
|
||||
body = get(API + submission_id)
|
||||
status = body["data"]["attributes"]["status"]
|
||||
except (KeyError, TypeError):
|
||||
print(f"::error::Unexpected notary API response for {submission_id}: {json.dumps(body)[:500]}")
|
||||
sys.exit(1)
|
||||
except urllib.error.HTTPError as error:
|
||||
if error.code < 500:
|
||||
print(f"::error::Notary API returned HTTP {error.code} for {submission_id}.")
|
||||
sys.exit(1)
|
||||
status = f"HTTP {error.code}, retrying"
|
||||
except urllib.error.URLError as error:
|
||||
status = f"network error ({error.reason}), retrying"
|
||||
print(time.strftime("%H:%M:%S"), status, flush=True)
|
||||
|
||||
if status == "Accepted":
|
||||
sys.exit(0)
|
||||
if status in ("Invalid", "Rejected"):
|
||||
print(f"::error::Apple returned {status} for notary submission {submission_id}.")
|
||||
log_url = get(API + submission_id + "/logs")["data"]["attributes"]["developerLogUrl"]
|
||||
print(json.dumps(get(log_url, auth=False), indent=2))
|
||||
sys.exit(1)
|
||||
if time.time() > deadline:
|
||||
print(f"::error::Notary submission {submission_id} is still In Progress at Apple. "
|
||||
"Nothing is lost: the signed app is kept as an artifact of this run. "
|
||||
"Use 'Re-run failed jobs' later to check the same submission again.")
|
||||
sys.exit(1)
|
||||
time.sleep(POLL_SECONDS)
|
||||
@ -0,0 +1,300 @@
|
||||
name: iOS signed build and upload
|
||||
|
||||
# Builds a signed IPA and uploads it to App Store Connect (#1038, epic #1013).
|
||||
# Called by testflight.yml and release-signed.yml.
|
||||
#
|
||||
# SECURITY: this repo is PUBLIC, and this job holds the Apple Distribution key
|
||||
# and the App Store Connect API key.
|
||||
#
|
||||
# - NEVER call this from a `pull_request` workflow. A PR (incl. from a fork)
|
||||
# must never run a job that can read these secrets.
|
||||
# - Only this job references the `apple-signing` Environment, so only it
|
||||
# receives them, and only after the required reviewer approves.
|
||||
# - Secret files live in RUNNER_TEMP or the key folder altool reads, and are
|
||||
# removed with `if: always()`.
|
||||
# - Values are passed via env:, never on a command line, never echoed.
|
||||
#
|
||||
# There is deliberately no dry-run or skip-upload input. A switch that lets this
|
||||
# go green without doing its job is the shape of the #904 override. A TestFlight
|
||||
# upload is private, so the lane proves itself by really uploading.
|
||||
#
|
||||
# Every step stops on the first thing it cannot confirm.
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
BUNDLE_ID: app.offband.meshcore.ios
|
||||
|
||||
jobs:
|
||||
ios-signed:
|
||||
runs-on: macos-latest
|
||||
environment: apple-signing # required-reviewer gate; do not remove
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Check the signing secrets are present
|
||||
env:
|
||||
APPLE_DIST_P12_BASE64: ${{ secrets.APPLE_DIST_P12_BASE64 }}
|
||||
APPLE_DIST_P12_PASSWORD: ${{ secrets.APPLE_DIST_P12_PASSWORD }}
|
||||
APPLE_PROFILE_BASE64: ${{ secrets.APPLE_PROFILE_BASE64 }}
|
||||
ASC_API_KEY_P8_BASE64: ${{ secrets.ASC_API_KEY_P8_BASE64 }}
|
||||
ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
|
||||
ASC_API_ISSUER_ID: ${{ secrets.ASC_API_ISSUER_ID }}
|
||||
run: |
|
||||
set -eu
|
||||
missing=0
|
||||
for name in APPLE_DIST_P12_BASE64 APPLE_DIST_P12_PASSWORD APPLE_PROFILE_BASE64 \
|
||||
ASC_API_KEY_P8_BASE64 ASC_API_KEY_ID ASC_API_ISSUER_ID; do
|
||||
if [ -z "${!name:-}" ]; then
|
||||
echo "::error::Secret ${name} is empty or absent in this run."
|
||||
missing=1
|
||||
fi
|
||||
done
|
||||
exit "${missing}"
|
||||
|
||||
- name: Temporary keychain with the Distribution identity
|
||||
env:
|
||||
APPLE_DIST_P12_BASE64: ${{ secrets.APPLE_DIST_P12_BASE64 }}
|
||||
APPLE_DIST_P12_PASSWORD: ${{ secrets.APPLE_DIST_P12_PASSWORD }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
KC="${RUNNER_TEMP}/signing.keychain-db"
|
||||
KP="$(openssl rand -hex 16)"
|
||||
echo "::add-mask::${KP}"
|
||||
echo "KC=${KC}" >> "$GITHUB_ENV"
|
||||
security create-keychain -p "${KP}" "${KC}"
|
||||
security set-keychain-settings -lut 21600 "${KC}"
|
||||
security unlock-keychain -p "${KP}" "${KC}"
|
||||
P12="${RUNNER_TEMP}/dist.p12"
|
||||
printf '%s' "${APPLE_DIST_P12_BASE64}" | base64 --decode > "${P12}"
|
||||
security import "${P12}" -k "${KC}" -P "${APPLE_DIST_P12_PASSWORD}" \
|
||||
-T /usr/bin/codesign -T /usr/bin/security
|
||||
rm -f "${P12}"
|
||||
security set-key-partition-list -S apple-tool:,apple: -s -k "${KP}" "${KC}" > /dev/null
|
||||
security list-keychains -d user -s "${KC}" $(security list-keychains -d user | tr -d '"')
|
||||
IDENTITIES="$(security find-identity -v -p codesigning "${KC}")"
|
||||
COUNT="$(printf '%s\n' "${IDENTITIES}" | grep -c '"Apple Distribution: ' || true)"
|
||||
if [ "${COUNT}" != "1" ]; then
|
||||
echo "::error::Expected one Apple Distribution identity in the keychain, found ${COUNT}."
|
||||
exit 1
|
||||
fi
|
||||
IDENTITY="$(printf '%s\n' "${IDENTITIES}" | sed -n 's/.*"\(Apple Distribution: .*\)".*/\1/p')"
|
||||
# Holds the owner's legal name, and env values appear in public step logs.
|
||||
echo "::add-mask::${IDENTITY}"
|
||||
echo "IDENTITY=${IDENTITY}" >> "$GITHUB_ENV"
|
||||
echo "Keychain ready with one Apple Distribution identity."
|
||||
|
||||
- name: Install the provisioning profile
|
||||
env:
|
||||
APPLE_PROFILE_BASE64: ${{ secrets.APPLE_PROFILE_BASE64 }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
PROFILE="${RUNNER_TEMP}/dist.mobileprovision"
|
||||
printf '%s' "${APPLE_PROFILE_BASE64}" | base64 --decode > "${PROFILE}"
|
||||
PLIST="${RUNNER_TEMP}/profile.plist"
|
||||
security cms -D -i "${PROFILE}" > "${PLIST}"
|
||||
PB=/usr/libexec/PlistBuddy
|
||||
UUID="$("${PB}" -c 'Print :UUID' "${PLIST}")"
|
||||
NAME="$("${PB}" -c 'Print :Name' "${PLIST}")"
|
||||
TEAM="$("${PB}" -c 'Print :TeamIdentifier:0' "${PLIST}")"
|
||||
APP_ID="$("${PB}" -c 'Print :Entitlements:application-identifier' "${PLIST}")"
|
||||
if [ -z "${UUID}" ] || [ -z "${NAME}" ] || [ -z "${TEAM}" ]; then
|
||||
echo "::error::Could not read the profile's UUID, name and team."
|
||||
exit 1
|
||||
fi
|
||||
if [ "${APP_ID}" != "${TEAM}.${BUNDLE_ID}" ]; then
|
||||
echo "::error::The profile is for ${APP_ID}, not ${TEAM}.${BUNDLE_ID}."
|
||||
exit 1
|
||||
fi
|
||||
# Xcode 16 and later read the second folder; older versions the first.
|
||||
for dir in "${HOME}/Library/MobileDevice/Provisioning Profiles" \
|
||||
"${HOME}/Library/Developer/Xcode/UserData/Provisioning Profiles"; do
|
||||
mkdir -p "${dir}"
|
||||
cp "${PROFILE}" "${dir}/${UUID}.mobileprovision"
|
||||
done
|
||||
rm -f "${PROFILE}" "${PLIST}"
|
||||
{
|
||||
echo "PROFILE_UUID=${UUID}"
|
||||
echo "PROFILE_NAME=${NAME}"
|
||||
echo "TEAM=${TEAM}"
|
||||
} >> "$GITHUB_ENV"
|
||||
echo "Profile '${NAME}' installed for ${BUNDLE_ID}."
|
||||
|
||||
# Only Runner's Release config includes this xcconfig, so CocoaPods targets
|
||||
# keep their own signing. Written here, not committed: the project stays
|
||||
# free of a team and profile, and the compile job in build.yml is untouched.
|
||||
- name: Apply manual signing and write ExportOptions.plist
|
||||
run: |
|
||||
set -eu
|
||||
{
|
||||
echo ""
|
||||
echo "CODE_SIGN_STYLE = Manual"
|
||||
echo "DEVELOPMENT_TEAM = ${TEAM}"
|
||||
echo "PROVISIONING_PROFILE_SPECIFIER = ${PROFILE_NAME}"
|
||||
echo "CODE_SIGN_IDENTITY = Apple Distribution"
|
||||
echo "CODE_SIGN_IDENTITY[sdk=iphoneos*] = Apple Distribution"
|
||||
} >> ios/Flutter/Release.xcconfig
|
||||
OPTIONS="${RUNNER_TEMP}/ExportOptions.plist"
|
||||
PB=/usr/libexec/PlistBuddy
|
||||
"${PB}" -c 'Add :method string app-store-connect' \
|
||||
-c 'Add :destination string export' \
|
||||
-c 'Add :signingStyle string manual' \
|
||||
-c 'Add :signingCertificate string Apple Distribution' \
|
||||
-c "Add :teamID string ${TEAM}" \
|
||||
-c 'Add :provisioningProfiles dict' \
|
||||
-c "Add :provisioningProfiles:${BUNDLE_ID} string ${PROFILE_NAME}" \
|
||||
"${OPTIONS}"
|
||||
echo "OPTIONS=${OPTIONS}" >> "$GITHUB_ENV"
|
||||
|
||||
- uses: subosito/flutter-action@v2
|
||||
with:
|
||||
flutter-version: "3.44.1"
|
||||
cache: true
|
||||
- run: flutter pub get
|
||||
- run: dart run build_runner build --delete-conflicting-outputs
|
||||
- name: Write dart_defines.json
|
||||
env:
|
||||
GIPHY_API_KEY: ${{ secrets.GIPHY_API_KEY }}
|
||||
run: jq -n --arg k "$GIPHY_API_KEY" '{GIPHY_API_KEY:$k}' > dart_defines.json
|
||||
|
||||
# The build number is the run ID, not the run number: testflight.yml and
|
||||
# release-signed.yml each count their own runs, so run numbers collide
|
||||
# between them, and Apple refuses a duplicate. A re-run reuses its ID, so
|
||||
# Apple refuses that too, which stops the job rather than hiding anything.
|
||||
- name: Build the signed IPA
|
||||
run: |
|
||||
set -eu
|
||||
BUILD_NAME="$(grep -E '^version:' pubspec.yaml | head -1 | sed 's/version:[[:space:]]*//' | sed 's/+.*//' | tr -d '[:space:]')"
|
||||
BUILD_NUMBER="${GITHUB_RUN_ID}"
|
||||
if [ -z "${BUILD_NAME}" ]; then
|
||||
echo "::error::Could not read the version from pubspec.yaml."
|
||||
exit 1
|
||||
fi
|
||||
echo "BUILD_NAME=${BUILD_NAME}" >> "$GITHUB_ENV"
|
||||
echo "BUILD_NUMBER=${BUILD_NUMBER}" >> "$GITHUB_ENV"
|
||||
echo "Building ${BUILD_NAME} (${BUILD_NUMBER})."
|
||||
flutter build ipa --release --no-pub \
|
||||
--build-name="${BUILD_NAME}" \
|
||||
--build-number="${BUILD_NUMBER}" \
|
||||
--dart-define-from-file=dart_defines.json \
|
||||
--export-options-plist="${OPTIONS}"
|
||||
|
||||
- name: Unpack the IPA
|
||||
run: |
|
||||
set -eu
|
||||
COUNT="$(ls build/ios/ipa/*.ipa 2>/dev/null | wc -l | tr -d ' ')"
|
||||
if [ "${COUNT}" != "1" ]; then
|
||||
echo "::error::Expected one IPA in build/ios/ipa, found ${COUNT}."
|
||||
exit 1
|
||||
fi
|
||||
IPA="$(ls build/ios/ipa/*.ipa)"
|
||||
echo "IPA=${IPA}" >> "$GITHUB_ENV"
|
||||
UNPACKED="${RUNNER_TEMP}/ipa"
|
||||
mkdir -p "${UNPACKED}"
|
||||
unzip -q "${IPA}" -d "${UNPACKED}"
|
||||
echo "APP=${UNPACKED}/Payload/Runner.app" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Assert the IPA holds its native-asset frameworks (#1037)
|
||||
run: bash .github/scripts/ios-assert-frameworks.sh "${APP}"
|
||||
|
||||
- name: Assert the IPA's identity and version
|
||||
run: |
|
||||
set -eu
|
||||
PB=/usr/libexec/PlistBuddy
|
||||
for pair in "CFBundleIdentifier=${BUNDLE_ID}" \
|
||||
"CFBundleShortVersionString=${BUILD_NAME}" \
|
||||
"CFBundleVersion=${BUILD_NUMBER}"; do
|
||||
KEY="${pair%%=*}"
|
||||
WANT="${pair#*=}"
|
||||
GOT="$("${PB}" -c "Print :${KEY}" "${APP}/Info.plist")"
|
||||
if [ "${GOT}" != "${WANT}" ]; then
|
||||
echo "::error::${KEY} is '${GOT}', expected '${WANT}'."
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
echo "Identity and version are as expected."
|
||||
|
||||
# A green build does not prove what signed it, the same reason the Android
|
||||
# job pins its certificate. The check runs against a wrong name first, so
|
||||
# it is shown able to fail on every run.
|
||||
- name: Verify the IPA is signed by the Distribution certificate
|
||||
run: |
|
||||
set -eu
|
||||
codesign --verify --deep --strict "${APP}"
|
||||
INFO="$(codesign -dvv "${APP}" 2>&1)"
|
||||
if printf '%s\n' "${INFO}" | grep -qxF "Authority=Apple Distribution: Not This Team (XXXXXXXXXX)"; then
|
||||
echo "::error::The signing check accepted a wrong certificate name."
|
||||
exit 1
|
||||
fi
|
||||
if ! printf '%s\n' "${INFO}" | grep -qxF "Authority=${IDENTITY}"; then
|
||||
echo "::error::The IPA is not signed by the Apple Distribution identity in the keychain."
|
||||
exit 1
|
||||
fi
|
||||
if ! printf '%s\n' "${INFO}" | grep -qxF "TeamIdentifier=${TEAM}"; then
|
||||
echo "::error::The IPA's team is not the profile's team."
|
||||
exit 1
|
||||
fi
|
||||
echo "IPA signing verified."
|
||||
|
||||
- name: Install the App Store Connect API key
|
||||
env:
|
||||
ASC_API_KEY_P8_BASE64: ${{ secrets.ASC_API_KEY_P8_BASE64 }}
|
||||
ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
KEY_DIR="${HOME}/.appstoreconnect/private_keys"
|
||||
mkdir -p "${KEY_DIR}"
|
||||
printf '%s' "${ASC_API_KEY_P8_BASE64}" | base64 --decode > "${KEY_DIR}/AuthKey_${ASC_API_KEY_ID}.p8"
|
||||
|
||||
# On the runner's own tool, so the key folder and subcommands are read, not
|
||||
# recalled (#1040). Prints only documentation.
|
||||
- name: Record what altool documents here
|
||||
run: |
|
||||
xcrun altool --version || true
|
||||
man altool 2>/dev/null | col -b | grep -n -i -E 'private_keys|--validate-app|--upload-app|--upload-package' || true
|
||||
|
||||
- name: Validate with App Store Connect
|
||||
env:
|
||||
ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
|
||||
ASC_API_ISSUER_ID: ${{ secrets.ASC_API_ISSUER_ID }}
|
||||
run: |
|
||||
set +e
|
||||
OUT="${RUNNER_TEMP}/altool-validate.txt"
|
||||
xcrun altool --validate-app -f "${IPA}" -t ios \
|
||||
--apiKey "${ASC_API_KEY_ID}" --apiIssuer "${ASC_API_ISSUER_ID}" > "${OUT}" 2>&1
|
||||
CODE=$?
|
||||
set -e
|
||||
cat "${OUT}"
|
||||
bash .github/scripts/ios-altool-check.sh validate "${CODE}" "${OUT}"
|
||||
|
||||
- name: Upload to App Store Connect
|
||||
env:
|
||||
ASC_API_KEY_ID: ${{ secrets.ASC_API_KEY_ID }}
|
||||
ASC_API_ISSUER_ID: ${{ secrets.ASC_API_ISSUER_ID }}
|
||||
run: |
|
||||
set +e
|
||||
OUT="${RUNNER_TEMP}/altool-upload.txt"
|
||||
xcrun altool --upload-app -f "${IPA}" -t ios \
|
||||
--apiKey "${ASC_API_KEY_ID}" --apiIssuer "${ASC_API_ISSUER_ID}" > "${OUT}" 2>&1
|
||||
CODE=$?
|
||||
set -e
|
||||
cat "${OUT}"
|
||||
bash .github/scripts/ios-altool-check.sh upload "${CODE}" "${OUT}"
|
||||
echo "Uploaded ${BUILD_NAME} (${BUILD_NUMBER})."
|
||||
|
||||
- name: Remove signing material
|
||||
if: always()
|
||||
run: |
|
||||
[ -n "${KC:-}" ] && security delete-keychain "${KC}" || true
|
||||
rm -rf "${HOME}/.appstoreconnect/private_keys"
|
||||
rm -f "${HOME}/Library/MobileDevice/Provisioning Profiles/"*.mobileprovision
|
||||
rm -f "${HOME}/Library/Developer/Xcode/UserData/Provisioning Profiles/"*.mobileprovision
|
||||
rm -f dart_defines.json "${RUNNER_TEMP}/dist.p12" "${RUNNER_TEMP}/dist.mobileprovision" "${RUNNER_TEMP}/profile.plist"
|
||||
echo "Signing material removed."
|
||||
@ -0,0 +1,147 @@
|
||||
name: iOS signing proof
|
||||
|
||||
# Proves, on the same macOS runner image the signed iOS lane will use, that a
|
||||
# .p12 packed the way tools/ios-signing/ios-signing.ps1 packs it imports into a
|
||||
# keychain with its private key paired to its certificate (#1016, epic #1012).
|
||||
#
|
||||
# Uses a THROWAWAY self-signed certificate generated here, every run. No real
|
||||
# identity, no secret, no private key in the repository. Nothing in this job can
|
||||
# reach the apple-signing Environment.
|
||||
#
|
||||
# Why it exists: OpenSSL 3 (which the owner's Windows script uses) writes .p12
|
||||
# files with PBES2/AES-256 and a SHA-256 MAC by default; older macOS keychain
|
||||
# tooling has refused that format. The script packs the legacy format
|
||||
# (3DES, SHA-1 MAC) instead, and this job is what shows the choice works.
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "tools/ios-signing/**"
|
||||
- ".github/workflows/ios-signing-proof.yml"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
p12-import:
|
||||
runs-on: macos-latest
|
||||
env:
|
||||
CN: "Offband CI throwaway"
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Locate OpenSSL 3
|
||||
run: |
|
||||
set -eu
|
||||
PREFIX="$(brew --prefix openssl@3 2>/dev/null || true)"
|
||||
OPENSSL="${PREFIX}/bin/openssl"
|
||||
if [ -z "${PREFIX}" ] || [ ! -x "${OPENSSL}" ]; then
|
||||
echo "::error::Homebrew openssl@3 not found on this runner; cannot reproduce the Windows script's OpenSSL 3 output."
|
||||
exit 1
|
||||
fi
|
||||
"${OPENSSL}" version
|
||||
echo "OPENSSL=${OPENSSL}" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Make a throwaway certificate and pack it both ways
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
W="${RUNNER_TEMP}/p12"
|
||||
mkdir -p "$W"
|
||||
PW="$("${OPENSSL}" rand -hex 16)"
|
||||
echo "::add-mask::${PW}"
|
||||
echo "P12_PW=${PW}" >> "$GITHUB_ENV"
|
||||
echo "W=${W}" >> "$GITHUB_ENV"
|
||||
"${OPENSSL}" req -x509 -newkey rsa:2048 -nodes -days 1 \
|
||||
-keyout "$W/k.pem" -out "$W/c.pem" -subj "/CN=${CN}"
|
||||
# The OpenSSL 3 default, for the record only.
|
||||
"${OPENSSL}" pkcs12 -export -inkey "$W/k.pem" -in "$W/c.pem" -name "${CN}" \
|
||||
-out "$W/default.p12" -passout "pass:${PW}"
|
||||
# The format the owner's script produces. Keep these flags identical
|
||||
# to tools/ios-signing/ios-signing.ps1.
|
||||
"${OPENSSL}" pkcs12 -export -inkey "$W/k.pem" -in "$W/c.pem" -name "${CN}" \
|
||||
-keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1 \
|
||||
-out "$W/legacy.p12" -passout "pass:${PW}"
|
||||
for f in default legacy; do
|
||||
test -s "$W/$f.p12" || { echo "::error::$f.p12 was not written"; exit 1; }
|
||||
echo "== $f.p12 =="
|
||||
"${OPENSSL}" pkcs12 -info -noout -in "$W/$f.p12" -passin "pass:${PW}" 2>&1 | grep -E "MAC:|Encrypted data|Shrouded"
|
||||
done
|
||||
|
||||
- name: Temporary keychain
|
||||
run: |
|
||||
set -eu
|
||||
KC="${RUNNER_TEMP}/proof.keychain-db"
|
||||
KP="$("${OPENSSL}" rand -hex 16)"
|
||||
echo "::add-mask::${KP}"
|
||||
security create-keychain -p "${KP}" "${KC}"
|
||||
security set-keychain-settings -lut 600 "${KC}"
|
||||
security unlock-keychain -p "${KP}" "${KC}"
|
||||
echo "KC=${KC}" >> "$GITHUB_ENV"
|
||||
|
||||
# The check that must be able to fail. If a wrong password were accepted,
|
||||
# every result below would be meaningless.
|
||||
- name: "Negative: wrong password is refused"
|
||||
run: |
|
||||
set -u
|
||||
if security import "${W}/legacy.p12" -k "${KC}" -P "not-the-password" -T /usr/bin/codesign; then
|
||||
echo "::error::A wrong password was accepted. This proof cannot be trusted."
|
||||
exit 1
|
||||
fi
|
||||
echo "Refused, as required."
|
||||
|
||||
- name: "Positive: legacy .p12 imports with its key paired"
|
||||
run: |
|
||||
set -eu
|
||||
security import "${W}/legacy.p12" -k "${KC}" -P "${P12_PW}" -T /usr/bin/codesign
|
||||
security find-certificate -c "${CN}" "${KC}" > /dev/null
|
||||
IDS="$(security find-identity "${KC}")"
|
||||
echo "${IDS}"
|
||||
if ! printf '%s\n' "${IDS}" | grep -q "${CN}"; then
|
||||
echo "::error::Certificate imported but no identity: the private key did not pair with it."
|
||||
exit 1
|
||||
fi
|
||||
echo "Legacy .p12 imported with key and certificate paired."
|
||||
|
||||
# The owner's script itself, not a copy of its flags: run its selftest
|
||||
# under PowerShell on this runner and import what it produced (#1017).
|
||||
- name: "Script: ios-signing.ps1 selftest output imports"
|
||||
run: |
|
||||
set -eu
|
||||
command -v pwsh > /dev/null || { echo "::error::pwsh not found on this runner"; exit 1; }
|
||||
OUT="${RUNNER_TEMP}/selftest"
|
||||
mkdir -p "${OUT}"
|
||||
OPENSSL="${OPENSSL}" SELFTEST_OUT="${OUT}" pwsh -NoProfile -File tools/ios-signing/ios-signing.ps1 selftest
|
||||
test -s "${OUT}/selftest.p12" || { echo "::error::selftest produced no .p12"; exit 1; }
|
||||
SPW="$(cat "${OUT}/selftest-password.txt")"
|
||||
echo "::add-mask::${SPW}"
|
||||
security import "${OUT}/selftest.p12" -k "${KC}" -P "${SPW}" -T /usr/bin/codesign
|
||||
IDS="$(security find-identity "${KC}")"
|
||||
if ! printf '%s\n' "${IDS}" | grep -q "Offband Meshcore Distribution"; then
|
||||
echo "${IDS}"
|
||||
echo "::error::The script's .p12 imported but its key did not pair with its certificate."
|
||||
exit 1
|
||||
fi
|
||||
rm -rf "${OUT}"
|
||||
echo "The script's own .p12 imports with key and certificate paired."
|
||||
|
||||
- name: "Record: does the OpenSSL 3 default import here too?"
|
||||
run: |
|
||||
set -u
|
||||
KC2="${RUNNER_TEMP}/default.keychain-db"
|
||||
security create-keychain -p tmp "${KC2}"
|
||||
security unlock-keychain -p tmp "${KC2}"
|
||||
if security import "${W}/default.p12" -k "${KC2}" -P "${P12_PW}" -T /usr/bin/codesign; then
|
||||
echo "::notice::The OpenSSL 3 default format also imports on this runner image."
|
||||
else
|
||||
echo "::notice::The OpenSSL 3 default format is REFUSED on this runner image; the legacy format is required."
|
||||
fi
|
||||
security delete-keychain "${KC2}" || true
|
||||
|
||||
- name: Clean up
|
||||
if: always()
|
||||
run: |
|
||||
[ -n "${KC:-}" ] && security delete-keychain "${KC}" || true
|
||||
[ -n "${W:-}" ] && rm -rf "${W}" || true
|
||||
echo "Throwaway keychain and files removed."
|
||||
@ -0,0 +1,232 @@
|
||||
name: macOS signed build
|
||||
|
||||
# Builds the macOS app, signs it with the Developer ID Application identity,
|
||||
# notarizes it with Apple and staples the ticket, so it opens on any Mac with
|
||||
# no Gatekeeper warning (#1109, epic #1107). Called by release-signed.yml.
|
||||
#
|
||||
# Three jobs, so no Mac runner ever sits waiting on Apple's queue:
|
||||
# 1. build-sign-submit (Mac): build, sign, submit, keep the signed app.
|
||||
# 2. notary-wait (Linux): poll Apple for that submission, up to 340 min.
|
||||
# 3. staple (Mac): staple the ticket, verify, publish the zip.
|
||||
# If Apple holds a submission past the poll deadline, job 2 fails, the signed
|
||||
# app stays an artifact of the run, and "Re-run failed jobs" checks the SAME
|
||||
# submission again later. Nothing is rebuilt or resubmitted.
|
||||
#
|
||||
# SEPARATION: this lane uses its own `apple-macos` Environment and its own
|
||||
# App Store Connect key. It shares no Environment, secret or key with the
|
||||
# iOS lane (`apple-signing`), so a hold, revocation or failure in one Apple
|
||||
# lane cannot break the other.
|
||||
#
|
||||
# SECURITY: this repo is PUBLIC, and jobs 1 and 2 hold the Developer ID key
|
||||
# and the notary API key.
|
||||
#
|
||||
# - NEVER call this from a `pull_request` workflow. A PR (incl. from a fork)
|
||||
# must never run a job that can read these secrets.
|
||||
# - Only jobs 1 and 2 reference the `apple-macos` Environment, so only they
|
||||
# receive secrets, and only after the required reviewer approves. Job 3
|
||||
# needs none: stapling fetches the public ticket by the app's hash.
|
||||
# - Secret files live in RUNNER_TEMP and are removed with `if: always()`.
|
||||
# - Values are passed via env:, never echoed. The identity name holds the
|
||||
# owner's legal name and is masked.
|
||||
#
|
||||
# There is deliberately no skip-notarization input: an unsigned or
|
||||
# unnotarized app must fail this lane, never pass it (#904).
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
build-sign-submit:
|
||||
runs-on: macos-latest
|
||||
environment: apple-macos # required-reviewer gate; do not remove
|
||||
timeout-minutes: 60
|
||||
outputs:
|
||||
submission-id: ${{ steps.submit.outputs.id }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Check the signing secrets are present
|
||||
env:
|
||||
MACOS_DEVID_P12_BASE64: ${{ secrets.MACOS_DEVID_P12_BASE64 }}
|
||||
MACOS_DEVID_P12_PASSWORD: ${{ secrets.MACOS_DEVID_P12_PASSWORD }}
|
||||
MACOS_NOTARY_KEY_P8_BASE64: ${{ secrets.MACOS_NOTARY_KEY_P8_BASE64 }}
|
||||
MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
|
||||
MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
|
||||
run: |
|
||||
set -eu
|
||||
missing=0
|
||||
for name in MACOS_DEVID_P12_BASE64 MACOS_DEVID_P12_PASSWORD \
|
||||
MACOS_NOTARY_KEY_P8_BASE64 MACOS_NOTARY_KEY_ID MACOS_NOTARY_ISSUER_ID; do
|
||||
if [ -z "${!name:-}" ]; then
|
||||
echo "::error::Secret ${name} is empty or absent in this run."
|
||||
missing=1
|
||||
fi
|
||||
done
|
||||
exit "${missing}"
|
||||
|
||||
- name: Temporary keychain with the Developer ID identity
|
||||
env:
|
||||
MACOS_DEVID_P12_BASE64: ${{ secrets.MACOS_DEVID_P12_BASE64 }}
|
||||
MACOS_DEVID_P12_PASSWORD: ${{ secrets.MACOS_DEVID_P12_PASSWORD }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
KC="${RUNNER_TEMP}/signing.keychain-db"
|
||||
KP="$(openssl rand -hex 16)"
|
||||
echo "::add-mask::${KP}"
|
||||
echo "KC=${KC}" >> "$GITHUB_ENV"
|
||||
security create-keychain -p "${KP}" "${KC}"
|
||||
security set-keychain-settings -lut 21600 "${KC}"
|
||||
security unlock-keychain -p "${KP}" "${KC}"
|
||||
P12="${RUNNER_TEMP}/devid.p12"
|
||||
printf '%s' "${MACOS_DEVID_P12_BASE64}" | base64 --decode > "${P12}"
|
||||
security import "${P12}" -k "${KC}" -P "${MACOS_DEVID_P12_PASSWORD}" \
|
||||
-T /usr/bin/codesign -T /usr/bin/security
|
||||
rm -f "${P12}"
|
||||
security set-key-partition-list -S apple-tool:,apple: -s -k "${KP}" "${KC}" > /dev/null
|
||||
security list-keychains -d user -s "${KC}" $(security list-keychains -d user | tr -d '"')
|
||||
IDENTITIES="$(security find-identity -v -p codesigning "${KC}")"
|
||||
COUNT="$(printf '%s\n' "${IDENTITIES}" | grep -c '"Developer ID Application: ' || true)"
|
||||
if [ "${COUNT}" != "1" ]; then
|
||||
echo "::error::Expected one Developer ID Application identity in the keychain, found ${COUNT}."
|
||||
exit 1
|
||||
fi
|
||||
IDENTITY="$(printf '%s\n' "${IDENTITIES}" | sed -n 's/.*"\(Developer ID Application: .*\)".*/\1/p')"
|
||||
echo "::add-mask::${IDENTITY}"
|
||||
echo "IDENTITY=${IDENTITY}" >> "$GITHUB_ENV"
|
||||
echo "Keychain ready with one Developer ID Application identity."
|
||||
|
||||
- uses: subosito/flutter-action@v2
|
||||
with:
|
||||
flutter-version: "3.44.1"
|
||||
cache: true
|
||||
- run: flutter pub get
|
||||
- run: dart run build_runner build --delete-conflicting-outputs
|
||||
- name: Write dart_defines.json
|
||||
env:
|
||||
GIPHY_API_KEY: ${{ secrets.GIPHY_API_KEY }}
|
||||
run: jq -n --arg k "$GIPHY_API_KEY" '{GIPHY_API_KEY:$k}' > dart_defines.json
|
||||
- name: Enable native assets (bundles sqlite3 + llamadart libs, #445)
|
||||
run: flutter config --enable-native-assets
|
||||
- run: flutter build macos --release --no-pub --dart-define-from-file=dart_defines.json
|
||||
|
||||
# Inside-out: every nested Mach-O first, then each framework bundle, then
|
||||
# the app with its entitlements. Hardened Runtime and a secure timestamp
|
||||
# are what notarization requires.
|
||||
- name: Sign with Developer ID
|
||||
run: |
|
||||
set -eu
|
||||
APP=build/macos/Build/Products/Release/offband_meshcore.app
|
||||
echo "APP=${APP}" >> "$GITHUB_ENV"
|
||||
SIGN=(codesign --force --options runtime --timestamp --sign "${IDENTITY}" --keychain "${KC}")
|
||||
while IFS= read -r -d '' f; do
|
||||
if file -b "${f}" | grep -q 'Mach-O'; then
|
||||
"${SIGN[@]}" "${f}"
|
||||
fi
|
||||
done < <(find "${APP}/Contents/Frameworks" -type f -print0)
|
||||
while IFS= read -r -d '' fw; do
|
||||
"${SIGN[@]}" "${fw}"
|
||||
done < <(find "${APP}/Contents/Frameworks" -depth -name '*.framework' -type d -print0)
|
||||
"${SIGN[@]}" --entitlements macos/Runner/Release.entitlements "${APP}"
|
||||
codesign --verify --deep --strict --verbose=2 "${APP}"
|
||||
lipo -archs "${APP}/Contents/MacOS/offband_meshcore"
|
||||
|
||||
# ditto, not zip: it preserves the .app bundle's symlinks (#1108). The
|
||||
# same zip is what Apple notarizes and what job 3 staples.
|
||||
- name: Zip the signed app
|
||||
run: ditto -c -k --keepParent "${APP}" offband-macos-signed.zip
|
||||
|
||||
# Upload only, no --wait: the verdict is job 2's business.
|
||||
- name: Submit for notarization
|
||||
id: submit
|
||||
env:
|
||||
MACOS_NOTARY_KEY_P8_BASE64: ${{ secrets.MACOS_NOTARY_KEY_P8_BASE64 }}
|
||||
MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
|
||||
MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
P8="${RUNNER_TEMP}/AuthKey.p8"
|
||||
printf '%s' "${MACOS_NOTARY_KEY_P8_BASE64}" | base64 --decode > "${P8}"
|
||||
OUT="${RUNNER_TEMP}/notarize.json"
|
||||
xcrun notarytool submit offband-macos-signed.zip --key "${P8}" \
|
||||
--key-id "${MACOS_NOTARY_KEY_ID}" --issuer "${MACOS_NOTARY_ISSUER_ID}" \
|
||||
--output-format json > "${OUT}"
|
||||
cat "${OUT}"
|
||||
ID="$(jq -r '.id // empty' "${OUT}")"
|
||||
if [ -z "${ID}" ]; then
|
||||
echo "::error::notarytool returned no submission id."
|
||||
exit 1
|
||||
fi
|
||||
echo "id=${ID}" >> "$GITHUB_OUTPUT"
|
||||
echo "Submitted for notarization: ${ID}"
|
||||
|
||||
# Kept 30 days so a held submission can be finished by a re-run.
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: macos-signed-unstapled
|
||||
path: offband-macos-signed.zip
|
||||
if-no-files-found: error
|
||||
retention-days: 30
|
||||
|
||||
- name: Remove the signing material
|
||||
if: always()
|
||||
run: |
|
||||
set +e
|
||||
if [ -n "${KC:-}" ]; then security delete-keychain "${KC}"; fi
|
||||
rm -f dart_defines.json "${RUNNER_TEMP}/devid.p12" "${RUNNER_TEMP}/AuthKey.p8"
|
||||
|
||||
notary-wait:
|
||||
needs: build-sign-submit
|
||||
runs-on: ubuntu-latest
|
||||
environment: apple-macos # holds the notary key; do not remove
|
||||
# GitHub's job limit is 360 minutes. A Linux runner on a public repo costs
|
||||
# nothing to keep polling, and a hold of a few hours then finishes with no
|
||||
# manual re-run. The poll deadline leaves room for setup inside the limit.
|
||||
timeout-minutes: 355
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- run: pip install --quiet "PyJWT[crypto]==2.10.1"
|
||||
- name: Wait for Apple's verdict (340 min max)
|
||||
env:
|
||||
SUBMISSION_ID: ${{ needs.build-sign-submit.outputs.submission-id }}
|
||||
MACOS_NOTARY_KEY_P8_BASE64: ${{ secrets.MACOS_NOTARY_KEY_P8_BASE64 }}
|
||||
NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
|
||||
NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
|
||||
run: |
|
||||
set -eu
|
||||
umask 077
|
||||
export P8="${RUNNER_TEMP}/AuthKey.p8"
|
||||
printf '%s' "${MACOS_NOTARY_KEY_P8_BASE64}" | base64 --decode > "${P8}"
|
||||
python3 .github/scripts/notary-wait.py "${SUBMISSION_ID}" 340
|
||||
- name: Remove the notary key
|
||||
if: always()
|
||||
run: rm -f "${RUNNER_TEMP}/AuthKey.p8"
|
||||
|
||||
staple:
|
||||
needs: notary-wait
|
||||
runs-on: macos-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: macos-signed-unstapled
|
||||
- name: Staple and verify
|
||||
run: |
|
||||
set -eu
|
||||
ditto -x -k offband-macos-signed.zip .
|
||||
APP=offband_meshcore.app
|
||||
xcrun stapler staple "${APP}"
|
||||
xcrun stapler validate "${APP}"
|
||||
codesign --verify --deep --strict --verbose=2 "${APP}"
|
||||
spctl --assess --type execute --verbose=4 "${APP}"
|
||||
ditto -c -k --keepParent "${APP}" offband-macos.zip
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: release-macos
|
||||
path: offband-macos.zip
|
||||
if-no-files-found: error
|
||||
retention-days: 7
|
||||
@ -0,0 +1,20 @@
|
||||
name: TestFlight
|
||||
|
||||
# A signed build uploaded to App Store Connect, on demand (#1039, epic #1013).
|
||||
# Dispatch it from a `v*` tag or `main`: the apple-signing Environment refuses
|
||||
# any other ref. NEVER add a `pull_request` trigger; see ios-signed.yml.
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: testflight
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
ios:
|
||||
uses: ./.github/workflows/ios-signed.yml
|
||||
secrets: inherit
|
||||
@ -0,0 +1,70 @@
|
||||
**Title:** Offband MeshCore 1.8.0, and Offband MeshCore is on the App Store
|
||||
|
||||
---
|
||||
|
||||
Offband MeshCore 1.8.0 is out. It's a channels release: message history now belongs to the
|
||||
channel itself rather than the slot it occupies on your radio, every channel write waits for
|
||||
the radio to confirm it, and the app no longer keeps history out of sight where it could
|
||||
reappear later.
|
||||
|
||||
Full release notes, downloads and known issues:
|
||||
https://github.com/OffbandMesh/meshcore-client/releases/tag/v1.8.0
|
||||
|
||||
### Now on iPhone
|
||||
|
||||
Offband MeshCore is on the App Store, for iOS 16.4 or newer:
|
||||
https://apps.apple.com/us/app/offband-meshcore/id6829124741
|
||||
|
||||
The App Store has 1.7.0 today. 1.8.0 goes up once Apple has reviewed it.
|
||||
|
||||
### Before you update
|
||||
|
||||
- **Hidden history is cleared.** On its first full sync with a radio, 1.8.0 deletes the
|
||||
stored history of any channel that radio no longer holds. Channels on your radio are not
|
||||
touched. If any slot went unanswered or erased, nothing is deleted. If a reflash erased the
|
||||
radio's channel storage, the app keeps the history and offers **Restore to radio**.
|
||||
- **Slot 0 is kept for Public on every radio.** On stock or older firmware without Public,
|
||||
that slot goes unused.
|
||||
- **New text is English-only for now** in the other 17 languages.
|
||||
|
||||
### What's new
|
||||
|
||||
- **Channels:** history, unread counts and notification settings follow the channel's key.
|
||||
Changing a key asks whether to keep or delete the history. Adds can't overwrite another
|
||||
channel. Public stays in slot 0 and can't be deleted. An incomplete sync keeps your list
|
||||
and offers Retry sync. Restore to radio puts back channels a radio lost and reports what
|
||||
it confirmed.
|
||||
- **Your radio's settings** (Offband firmware 1.7.0 or newer): per-channel Radio sound,
|
||||
separate from phone notifications, plus display mode, status LED and display rotation.
|
||||
- **Any radio:** BLE pairing PIN and Factory Reset, with an option to delete that radio's data
|
||||
from the app.
|
||||
- **Fixed:** blocks stored on the radio, Serial capture's radio log, CoreScope observer counts
|
||||
and observer settings could be hidden by a firmware version check.
|
||||
- **macOS:** a desktop build signed and notarized by Apple is part of each release. It appears
|
||||
on the release page once Apple accepts it. It's new and hasn't had a full test pass.
|
||||
- Share logs and About work without a radio. Bluetooth scan errors stay on screen. Every map
|
||||
shows the OpenStreetMap credit. Long menus scroll, and links beside @mentions can be tapped.
|
||||
|
||||
### Known issues
|
||||
|
||||
- A channel's phone notifications set to Off can still notify (#1121).
|
||||
- A factory reset deletes the app data only on the phone that sent it (#1123).
|
||||
- On a T1000-E, QCC badge or Heltec T096 running firmware 1.7.0, the Status LED switch
|
||||
appears but the radio refuses it (#1132).
|
||||
- A Display or LED change can be undone by an older reading arriving just after it (#1124).
|
||||
- A contact add the radio refuses because its table is full shows as added (#1028).
|
||||
- On a T1000-E, Position Reporting Interval says it saved when the radio refused it (#1134).
|
||||
|
||||
### Get it
|
||||
|
||||
- **Android:** [Google Play](https://play.google.com/store/apps/details?id=app.offband.meshcore),
|
||||
rolling out in stages, or the APK on the release page
|
||||
- **iPhone:** [App Store](https://apps.apple.com/us/app/offband-meshcore/id6829124741)
|
||||
- **Windows, macOS, Linux:** [v1.8.0 release](https://github.com/OffbandMesh/meshcore-client/releases/tag/v1.8.0)
|
||||
- **Browser:** https://offband.app
|
||||
- **Offband firmware 1.7.0:** [offband-v1.7.0](https://github.com/OffbandMesh/meshcore-firmware/releases/tag/offband-v1.7.0)
|
||||
|
||||
Questions go in [Q&A](https://github.com/OffbandMesh/meshcore-client/discussions/categories/q-a)
|
||||
and bugs in [Issues](https://github.com/OffbandMesh/meshcore-client/issues). Thanks to the
|
||||
[OKIMesh community](https://okimesh.org/). If you'd like to help keep Offband going:
|
||||
https://offband.org/donate
|
||||
@ -0,0 +1,17 @@
|
||||
# GitHub Discussions announcement
|
||||
|
||||
One file per release: `announcements/<version>.md`, e.g. `announcements/1.8.0.md`.
|
||||
|
||||
## Style
|
||||
|
||||
A post for the **Announcements** category of this repo's GitHub Discussions. It's for people
|
||||
who follow the project on GitHub: what landed, anything to read before updating, every known
|
||||
issue that ships, and where to get each platform. Plainer than the Discord text, shorter than
|
||||
the release notes, and it links to the release page for the full notes.
|
||||
|
||||
The first line gives the discussion title (`**Title:** ...`), followed by a `---` line. The
|
||||
post body is everything after that.
|
||||
|
||||
**The post goes up after the release is published**, because it links to the release page.
|
||||
Only the owner posts it, or an agent on the owner's word. CI never posts it, and the release
|
||||
gate (`.github/scripts/release-gate.sh`) does not check this file.
|
||||
@ -0,0 +1,25 @@
|
||||
🚀 **Offband MeshCore 1.8.0 is out.** A channels release: your message history now belongs to the channel, not to whichever slot it sits in on your radio.
|
||||
|
||||
📱 **And it's on iPhone.** Offband MeshCore is now on the App Store (iOS 16.4 or newer): https://apps.apple.com/us/app/offband-meshcore/id6829124741. The App Store has 1.7.0 right now; 1.8.0 goes up once Apple has reviewed it.
|
||||
|
||||
⚠️ **Heads up before updating.** Older versions could keep a channel's messages hidden after the channel left your radio, and bring them back later. 1.8.0 doesn't. On its first full sync, it deletes stored history for any channel your radio no longer holds. Channels still on your radio are untouched. If a reflash wiped the radio's channel storage, the app spots it, keeps the history, and offers **Restore to radio** instead.
|
||||
|
||||
📡 **Channels you can trust.** History and unread counts follow the channel's key, so a channel that moves slots keeps them. Changing a channel's key asks whether to **keep** or **delete** its history. Adds can't overwrite another channel. Public always lives in slot 0, can't be deleted, and typing "public" as a hashtag gets you the real Public. An incomplete sync keeps your list and offers **Retry sync**.
|
||||
|
||||
🔔 **Your radio's own settings** (needs Offband firmware 1.7.0): choose per channel whether the radio itself beeps for everything, mentions only, or nothing, separately from your phone. **Display and LED** settings, including rotation for an upside-down screen. (On a T1000-E, QCC badge or Heltec T096, the Status LED switch still shows on firmware 1.7.0 but the radio won't take it; a later firmware release lets the app hide it.) Settings from 1.7.0 like GPS power save and custom tunes show up now too.
|
||||
|
||||
🔐 **Also:** set your radio's **BLE pairing PIN**, and **Factory Reset** from Settings (with a box to also clear that radio's data from the app).
|
||||
|
||||
🍎 **macOS build** now on every release, signed and notarized by Apple, so it opens like any other app. It lands on the release page once Apple's check finishes, which can trail the other downloads.
|
||||
|
||||
🔧 **Fixes and polish.** Radio-side blocks, Serial capture's radio log, CoreScope observer counts and observer settings no longer get hidden by a firmware version check. Share logs and About work without a radio, Bluetooth scan errors stay on screen, the OpenStreetMap credit is on every map, long menus scroll, and links next to @mentions are tappable. New text is English-only for now in other languages.
|
||||
|
||||
🐛 **Known issues** (full list in the release notes): a channel's phone notifications set to Off can still notify, a factory reset only clears the app data on the phone that sent it, and on a T1000-E the Position Reporting Interval says it saved when the radio refused it.
|
||||
|
||||
**📥 Get it on Google Play:** search **Offband MeshCore**, or https://play.google.com/store/apps/details?id=app.offband.meshcore (rolling out in stages, so it may take a few days to reach you)
|
||||
📱 **iPhone, on the App Store:** https://apps.apple.com/us/app/offband-meshcore/id6829124741 (1.8.0 follows Apple's review)
|
||||
💻 **Desktop (Windows / macOS / Linux) and Android APK:** https://github.com/OffbandMesh/meshcore-client/releases/tag/v1.8.0
|
||||
🌐 **Or run it in your browser:** https://offband.app
|
||||
📻 **Offband firmware 1.7.0:** https://github.com/OffbandMesh/meshcore-firmware/releases/tag/offband-v1.7.0
|
||||
|
||||
💚 Thanks as always to the **OKIMesh community** (https://okimesh.org/). Offband is open source and always will be; if you'd like to help keep it going: https://offband.org/donate
|
||||
@ -0,0 +1,202 @@
|
||||
# Feature PLAN: Play publishing automation
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Feature** | [#1053](https://github.com/OffbandMesh/meshcore-client/issues/1053) · Citadel `meshcore-open-sme` |
|
||||
| **Serves** | Standalone. Extends the release pipeline (epic #312) and mirrors the iOS lane (#1013). |
|
||||
| **Status** | Owner approved 2026-11-03 ("Plan approved."). Review fixes applied afterwards (section 12). In force when this PR merges. |
|
||||
| **Owner** | @Strycher |
|
||||
| **Last updated** | 2026-11-03 |
|
||||
|
||||
## At a glance
|
||||
|
||||
- **What:** a tagged release reaches Play through CI. You send it to External (Play's closed testing) or straight to production, and promote from External to production when you're ready. Test builds stay `adb` sideloads.
|
||||
- **Why now:** a cut takes five manual Play steps.
|
||||
- **How:** two Epics. API access and the upload tool, then the publish workflow.
|
||||
- **Done when:** a release reaches External or production from one word to me and one click from you, with no file handling.
|
||||
|
||||
### What a cut looks like afterwards
|
||||
|
||||
| Step | Today | Afterwards |
|
||||
|---|---|---|
|
||||
| Read the release texts, say "tag it" | You | You |
|
||||
| Approve signing on the run | You | You |
|
||||
| Bump `+N` in `pubspec` | Me, at the cut | Me, at the cut (unchanged) |
|
||||
| Get the AAB | Me, into Downloads | Gone. It stays on the GitHub release, where CI reads it. |
|
||||
| Upload, paste notes, name the release | You | CI, from `play/<version>.txt` |
|
||||
| Send to External or production | You, in Console | You say "External" or "production at N%", I dispatch it, you approve one click |
|
||||
| Move from External to production | You, in Console | You say "production at N%", I dispatch it, you approve one click |
|
||||
| Post to Discord | You | You (unchanged, CI never sends) |
|
||||
|
||||
### Things you should know up front
|
||||
|
||||
1. **Test builds never touch Play.** Every upload uses a version code forever, so only tagged releases upload, one code per release, as today. Test builds stay `adb` sideloads.
|
||||
2. **External goes to your whole closed tester list,** after Google's review. Production takes `draft` or a percentage.
|
||||
3. **Anyone opted in to Internal testing gets only Internal builds.** Google says they aren't eligible for closed or open builds. Nothing will upload to Internal, so anyone already opted in, your phone included, needs to opt out of Internal to get External builds.
|
||||
4. **The workflow can only be proven on a real release.** It runs only from a `v*` tag, so its live proof is the next cut.
|
||||
5. **`release-signed.yml` gets one small addition:** a provenance attestation on the AAB, so the publish workflow can prove the file it sends to Play is the one the signed run built. Added after review (section 12).
|
||||
|
||||
## 1. Diagnosis
|
||||
|
||||
| # | Finding | Evidence | Effect |
|
||||
|---|---|---|---|
|
||||
| 1 | No Play API access exists. The only Google credentials are a user login and ADC for reporting. | `gh secret list`, `gcloud auth list`. `CLAUDE.local.md` records that the user token cannot get a Play scope. | A new service account is required. |
|
||||
| 2 | `release-signed.yml` builds a signed AAB, attaches it to the GitHub release, and stops. | `release-signed.yml` android and release jobs. | Everything after that is manual. |
|
||||
| 3 | A version code can never be reused, and Play has seen up to 68. | Android docs: "You can't upload an APK to the Play Store with a `versionCode` you have already used." Bucket stats list 64, 65, 67, 68. | Uploading test builds would use up codes. Only releases upload. |
|
||||
| 4 | The closed testing track already exists and has been used. Open testing never was. | Cuts #214, #265 (1.1.2), #563 (1.5.0-beta.1). #159: "Open testing skipped." | External is that track. |
|
||||
| 5 | Internal testers receive only Internal builds. | Play help, "Version code requirements." | Item 3 of the up-front list. |
|
||||
| 6 | Release assets can be replaced after publishing, and a local release-signed build carries the same certificate and version code. Workflow artifacts expire after 7 days. | `release-signed.yml`: `gh release upload --clobber` on re-run, `retention-days: 7`. | A certificate and version code check can't tell the CI build from a local one. Provenance can. |
|
||||
|
||||
## 2. Scope
|
||||
|
||||
**In:**
|
||||
- One Google service account, keyless, usable only from CI.
|
||||
- `tools/play/`: the upload tool and its tests.
|
||||
- `play-publish.yml`: send a tagged release to External or production, and promote External to production.
|
||||
- A provenance attestation on the AAB in `release-signed.yml`.
|
||||
- The cut runbook update.
|
||||
|
||||
**Out:**
|
||||
- Test builds to Play on any track, and internal app sharing. Test builds stay sideloads.
|
||||
- Open testing.
|
||||
- Store listing text and screenshots through the API.
|
||||
- Discord. It stays human-pasted.
|
||||
- Uploading native debug symbols for named ANR frames. Worth doing next, separately.
|
||||
- Halting or narrowing a rollout from CI. Console does that in one click.
|
||||
- Any other change to `release-signed.yml`.
|
||||
|
||||
## 3. Epics
|
||||
|
||||
### Epic A: API access and the tool
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **A1 · Tool, tests first:** `tools/play/play_release.py`, standard library only. Given the AAB, the tag, a track and a rollout: checks the certificate against the pin `release-signed.yml` uses, checks the bundle's version code matches the tag's `pubspec`, and checks the code is higher than everything on Play unless Play already holds this exact release. Then builds the edit, uploads only if Play doesn't have the bundle, sets the track with the notes, and commits. Track status: `draft` stays `draft`; 100 is `completed`; 10, 25 or 50 is `inProgress` with that fraction, production only. Idempotent: if the track already carries this release at the requested rollout or wider, it reports success and changes nothing, so a re-run after a lost result is safe. It never removes another release from a track, and stops if the target track has a different version mid-rollout. A failed run deletes its uncommitted edit. Tests prove each refusal in section 6 by failing first. | 3 |
|
||||
| **A2 · Identity:** in the existing `offband-reporting` project, enable the Android Publisher API and create one service account, `play-publisher`, with a GitHub keyless (Workload Identity) pool. Its condition requires all of: this repo's numeric ID, the `play-release` environment, a tag ref starting `refs/tags/v`, and `workflow_ref` naming `play-publish.yml` at that tag. The environment's own deployment policy also allows only `v*` tags. No JSON key is ever created, and no Play credential exists on this machine. **Owner steps:** invite the account in Play Console, limited to this app, with "Release to production, exclude devices, and use Play App Signing" and "Release apps to testing tracks". Confirm the closed track's tester list is still who you want. | 3 |
|
||||
| **A3 · Epic verification:** a read-only dispatch lists every track and its version codes, which proves the identity works and reads the real track names. Then the negative test: a dispatch from anything but a `v*` tag must be refused. Also settles the provenance check B0 relies on: `gh attestation verify --source-ref` passes for an attested public release at its own tag and fails when given a different tag. | 2 |
|
||||
|
||||
### Epic B: the publish workflow
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **B0 · Provenance:** the `android` job in `release-signed.yml` attests the AAB with `actions/attest-build-provenance`. Before anything reaches Play, the publish workflow runs `gh attestation verify` with `--signer-workflow` set to `release-signed.yml`, `--source-ref` set to the tag, and `--deny-self-hosted-runners`. A file swapped onto the release, or built anywhere else, fails. | 2 |
|
||||
| **B1 · Workflow:** `play-publish.yml`, `workflow_dispatch` only, from a `v*` tag. One `concurrency` group for the whole app, never cancelling a run in progress, so two dispatches can't race on Play's edits. Refuses a tag whose commit isn't on `main`, so a tag pushed onto an unreviewed commit can't publish even if its signing run was approved. Permissions: `contents: read`, `attestations: read`, and `id-token: write` for the keyless token. Inputs: `target` (`external` or `production`) and `rollout` (`draft`, 10, 25, 50 or 100; External takes `draft` or 100). Downloads `app-release.aab` from that tag's GitHub release and runs the tool. New environment `play-release`, you as reviewer. No `pull_request` trigger, no keystore. The first dispatch for a tag uploads; later ones move the same bundle, so External and production get the same bytes. Re-dispatching a higher percentage widens a production rollout. | 3 |
|
||||
| **B2 · Cut runbook:** the new steps go in `CLAUDE.local.md` and my cut notes, and the AAB download to Downloads is dropped. | 1 |
|
||||
| **B3 · Epic verification:** static checks at merge. The live proof is the next real cut, through whichever route you choose. The other route is proven the first time you use it. This task stays open until both have run. | 2 |
|
||||
|
||||
## 4. Order and dependencies
|
||||
|
||||
A, then B. B0 adds two permissions and one step to the `android` job in `release-signed.yml`. The open iOS PR #1042 adds a separate `ios` job to the same file, so B0 rebases over it if it lands first, coordinated with that session through Agent Mail.
|
||||
|
||||
## 5. Grants and authorization
|
||||
|
||||
| Term | Proposed | Why |
|
||||
|---|---|---|
|
||||
| **What merging this plan authorizes** | Creating the Google identity in A2, and building Epics A and B. | Tier 2. Rollback: delete the account and the pool, and remove it from Play Console. |
|
||||
| **Merges** | 2 | One PR per Epic. |
|
||||
| **Epic verification** | Owner | CI config and a live credential; no test command can vouch for it alone. |
|
||||
| **Owner steps during the run** | Console invite and a look at the closed track's tester list (A2). Opting out of Internal if you joined it. | Everything else I run. |
|
||||
| **Stops** | Any refusal in section 6. | |
|
||||
| **Flash** | None | |
|
||||
|
||||
Epics: A is #1082, B is #1083.
|
||||
|
||||
```grant-terms
|
||||
{
|
||||
"epic_chain": [1082, 1083],
|
||||
"chain": true,
|
||||
"verification": { "mode": "owner" },
|
||||
"merge": { "budget": 2, "basis": "Two Epics, one PR each. The plan PR merges before this grant exists." },
|
||||
"flash": null,
|
||||
"reset": null,
|
||||
"expires_after_hours": 168
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Can't-tell branches
|
||||
|
||||
| Where | Can't tell what | Does |
|
||||
|---|---|---|
|
||||
| Identity | Token unavailable, or wrong repo, environment or ref | **stop** |
|
||||
| Source | The tag's commit isn't on `main` | **stop** |
|
||||
| Bundle | The tag's GitHub release has no AAB | **stop** |
|
||||
| Bundle | No provenance attestation, or one not from `release-signed.yml` at this tag | **stop** |
|
||||
| Bundle | Certificate does not match the pin, or is the debug key | **stop** |
|
||||
| Bundle | Version code differs from the tag's `pubspec` | **stop** |
|
||||
| Numbering | Tracks unreadable | **stop** |
|
||||
| Numbering | Code not higher than Play's highest, and not already this release | **stop** |
|
||||
| Notes | Missing, empty, or over 500 characters | **stop** |
|
||||
| Target | External given a percentage below 100 | **stop**. External goes to its whole tester list. |
|
||||
| Target | Requested rollout is narrower than what the track already serves | **stop**. Narrowing or halting is done in Console. |
|
||||
| Target | A different version is mid-rollout on the target track | **stop**. Finish or halt it in Console first. |
|
||||
| Target | Track already carries this release at the requested rollout or wider | Succeeds and changes nothing. Both states are known. |
|
||||
| Review | Play will not auto-send for review (for example, after a rejection) | **stop** and show Play's message. It never retries with review skipped. |
|
||||
|
||||
## 7. Verification
|
||||
|
||||
- **Named command:** `python -m unittest discover -s tools/play`, added to a PR check.
|
||||
- **Acceptance bar:** A3's track listing and refusal seen live, then B3's first real release.
|
||||
|
||||
**Not verified yet, and how each gets settled:**
|
||||
|
||||
| Claim | Status | Settled by |
|
||||
|---|---|---|
|
||||
| Closed testing's API track name is `alpha`. | Docs only | A3 reads the real names |
|
||||
| A keyless GitHub token can be exchanged for a Play-scoped token. | Believed, untested | A3 |
|
||||
| A bundle already on Play can be set on another track without re-uploading. | Believed, untested | B3 |
|
||||
| `gh attestation verify --source-ref` accepts the right tag and rejects a different one. | Flag confirmed in `gh` help; behavior untested | A3, before B is built |
|
||||
|
||||
## 8. Done when
|
||||
|
||||
- A release reaches External or production from one word to me and one click from you, with no file handling.
|
||||
- A release on External reaches production with one more.
|
||||
- No Google key file exists anywhere, and no Play credential exists on this machine.
|
||||
- Test builds never touch Play.
|
||||
|
||||
## 9. Decisions
|
||||
|
||||
| # | Question | Decision |
|
||||
|---|---|---|
|
||||
| 1 | Where does a release go after signing? | Nowhere until you choose. Then External, or straight to production. From External, on to production. (2026-11-01, revised 2026-11-03) |
|
||||
| 2 | Do test builds go to Play? | No. They stay sideloads, so no version codes are used on them. (2026-11-03) |
|
||||
|
||||
## 10. Alternatives considered but not chosen
|
||||
|
||||
- **Test builds on the Internal track:** each one uses a version code. You declined it on 2026-11-03.
|
||||
- **Internal app sharing for test builds:** uses no version codes, but means a new link per build, 100 people per link, links expire after 60 days, and no automatic updates. Not asked for.
|
||||
- **Uploading to External automatically on every tag:** every tag would reach testers before you decided. A dispatch keeps it your call.
|
||||
- **Open testing as External:** anyone with the link could join. Closed testing keeps External to the people you list.
|
||||
- **A JSON key in a GitHub secret:** a long-lived credential in a public repo's settings. The keyless route needs none.
|
||||
- **Reading the next version code from Play:** only needed if test builds uploaded. `pubspec` stays the source, and the tool refuses a code Play has already passed.
|
||||
- **`fastlane` or a third-party upload action:** adds a dependency that handles publishing credentials, for four REST calls.
|
||||
|
||||
## 11. Carried-in work
|
||||
|
||||
| Item | Goes to |
|
||||
|---|---|
|
||||
| Native debug symbols for ANR traces (#931) | Separate follow-up after this Feature. |
|
||||
|
||||
When this plan merges, each Epic and Task gets a GitHub issue and a Citadel task, per canon.
|
||||
|
||||
## 12. Review
|
||||
|
||||
Gemini 2.5 Pro adversarial review, 2026-11-03, after owner approval.
|
||||
|
||||
| Finding | Severity | Outcome |
|
||||
|---|---|---|
|
||||
| Keyless condition only named repo and environment | High | **Fixed** in A2: repo ID, environment, `v*` tag ref and `workflow_ref` all required. |
|
||||
| A swapped release asset passes the certificate and version code check | High | **Fixed** with B0's provenance attestation. Gemini's proposed fix, reading the signed run's workflow artifact, doesn't work here: those artifacts expire after 7 days, and External to production can take longer. |
|
||||
| Closed track rejects a percentage | Medium | Already excluded: External takes `draft` or 100. A1 now spells out the status for each input. |
|
||||
| Re-runs and concurrent dispatches | Medium | **Fixed:** idempotent tool (A1), one concurrency group (B1), two new section 6 rows. |
|
||||
| `draft` meaning unclear | Low | **Clarified** in A1: the release sits on the chosen track unserved, and a later dispatch with a percentage or 100 publishes it. |
|
||||
| Closed track name may not be `alpha` | Low | Already settled by A3 reading the real names. No change. |
|
||||
|
||||
Second pass, same day, on the revision:
|
||||
|
||||
| Finding | Severity | Outcome |
|
||||
|---|---|---|
|
||||
| A `v*` tag pushed onto an unreviewed commit passes every check | High | **Fixed** in B1: the tag's commit must be on `main`, a protected branch that changes only through the promote PR. Gemini's proposed fix, a tag ruleset limiting who creates `v*` tags, would block the agent that cuts releases. |
|
||||
| A re-run of `release-signed.yml` replaces the AAB with `--clobber` | Medium | **No change.** A re-run needs your approval on `release-signing` again. Once Play holds a version code, it refuses any other bundle with that code, so a later swap can't reach Play. |
|
||||
| Verify step needs `id-token: read` | Low | **Corrected:** `id-token` has no read level. B1 now lists `attestations: read`, plus `id-token: write` for the keyless token. |
|
||||
| Adding a release could knock out another version mid-rollout | Medium | **Fixed** in A1 and section 6: never removes another release; stops on a different version mid-rollout. |
|
||||
| The provenance check is untested | Medium | **Fixed:** moved into A3, so it's proven before Epic B is built. |
|
||||
@ -0,0 +1,95 @@
|
||||
# Channel identity alignment: erased slots and slot-keyed notify (#1060)
|
||||
|
||||
Agent: CalmBay. Branch `feat/1068-radio-channel-notify`. No push, no PR.
|
||||
|
||||
## 1. Who owns the "key by identity, not slot" work
|
||||
|
||||
**Feature #1061, agent TurquoiseBridge (session 82d77b2f).** The identity key is
|
||||
the channel's **PSK hex**, not a pubkey; channels have no pubkey, and the PSK is
|
||||
what both history and settings already hang off.
|
||||
|
||||
| Issue | What | State |
|
||||
|---|---|---|
|
||||
| #1060 | the bug: slot map diverges after wipe + re-import, wrong-channel notifications | open |
|
||||
| #1061 | feature: channel state follows channel identity | open |
|
||||
| #1062 | fail-closed sync, ingress barrier, slot identity diff | landed |
|
||||
| #1063 | message history keyed by channel identity | landed |
|
||||
| #1064 | integration testing + #1060 bug validation | **open** |
|
||||
|
||||
The pattern itself is older than #1061: `feat(#260)` (2026-07-17) introduced
|
||||
PSK-keyed notify storage, `fix(#848)` scoped it per radio and killed the index
|
||||
fallback, and `#194` keyed message history the same way.
|
||||
|
||||
`test/connector/channel_slot_resync_integration_test.dart` already encodes the
|
||||
exact field case, down to `#wardriving` set to OFF.
|
||||
|
||||
## 2. What was still slot-keyed
|
||||
|
||||
#544 (epics #1068-#1071, this branch) added the RADIO-side per-channel notify
|
||||
after #1061 landed, and keyed it by **slot index**:
|
||||
|
||||
```dart
|
||||
final Map<int, RadioChannelNotify> _channelNotifyModes = {};
|
||||
```
|
||||
|
||||
That re-opened the exact class of defect #1061 was built to close, on the one
|
||||
surface where the user notices it fastest: the buzzer. The slot-identity-change
|
||||
handler cleared `_channelMessages[slot]` but not `_channelNotifyModes[slot]`,
|
||||
so after a slot shift the new occupant inherited the old one's mode.
|
||||
|
||||
Reproduced by planting the slot-keyed map back and running the new A5 test:
|
||||
|
||||
```
|
||||
Expected: null
|
||||
Actual: RadioChannelNotify:<RadioChannelNotify.off>
|
||||
```
|
||||
|
||||
A channel silenced on the radio handing its Off to whatever took its slot, and
|
||||
losing its own. That is the chirping.
|
||||
|
||||
### Fixed
|
||||
|
||||
- `_channelNotifyModes` is keyed by **PSK hex**. The wire stays slot-addressed;
|
||||
the slot is resolved to an identity at the wire edge and nowhere else.
|
||||
- A reply whose slot does not resolve to a confirmed channel is **dropped**,
|
||||
not stored against a slot number.
|
||||
- `setChannelNotify` takes a `Channel` and resolves its **current** slot at
|
||||
send time, so a `Channel` a widget captured before a re-sync cannot address a
|
||||
stale slot. Unresolvable means a visible refusal, no frame.
|
||||
|
||||
## 3. The erased-slot defect
|
||||
|
||||
Erased flash reads back as `0xFF`. `Channel.isEmpty` tests for `0x00`, so an
|
||||
erased record is not empty: it was adopted as a channel, rendered with U+FFFD
|
||||
replacement characters, and then **saved over the client's own good list**.
|
||||
|
||||
That is one missing validation gate, not two defects. The rendering and the
|
||||
overwrite are the same hole seen twice.
|
||||
|
||||
### Fixed
|
||||
|
||||
- `Channel.isErased` / `isUnusable`: an all-`0xFF` record, or a name that did
|
||||
not decode, is never adopted.
|
||||
- A sync that sees an erased slot **keeps the cached list** instead of
|
||||
overwriting it, reusing the fail-closed branch #1062 already had for holes.
|
||||
- `restoreChannelsToRadio()` writes the cached channels back to their own
|
||||
slots, with their PSKs, so history and settings line up again. Surfaced as an
|
||||
undismissable banner with a confirmed **Restore to radio** action.
|
||||
|
||||
Probe: forcing `isErased => false` turns 5 of the new tests red, including the
|
||||
cache overwrite.
|
||||
|
||||
## 4. Recovery for the list already lost
|
||||
|
||||
Not built, flagged for a decision. Message history keys are
|
||||
`channel_messages_<devicePrefix>psk_<pskHex>`, so **the PSKs of the lost
|
||||
channels still exist in the message store** even though the channel list was
|
||||
overwritten. A recovery pass could enumerate those keys and rebuild the list.
|
||||
Names would need retyping; the PSK is the part that matters.
|
||||
|
||||
## 5. State
|
||||
|
||||
`flutter analyze` clean. **1885 tests pass, 1 skipped.** New strings are
|
||||
English-only with `untranslated.json` regenerated.
|
||||
|
||||
Not pushed, no PR: the owner's gate is a hardware test first.
|
||||
@ -0,0 +1,45 @@
|
||||
# Feature #1061 channel slot resync truth: OUTCOMES
|
||||
|
||||
Status: BUILT and machine-verified; PRs opened on the owner's word (decision below), validation moves to live testing after merge. Branch stack: `feat/1062-channel-sync-truth` (Epic A) ← `feat/1063-message-state-hardening` (Epics B + C), rebased onto dev `180c01e6`.
|
||||
|
||||
## What was built
|
||||
| Epic | Commit | Content |
|
||||
|---|---|---|
|
||||
| A #1062 | `da08b7eb` | fail-closed atomic sync (no backfill, unconfirmed slots tracked + bannered with Retry, cache kept on holes), ingress barrier (messages held unbounded, raw sniffs bounded 64, flush post-sync), per-slot PSK identity diff (UI notice + warn log), unread preserved only on same PSK, fail-closed `_findChannelByIndex`, notification suppression for unconfirmed slots, self-retry on failed live sync |
|
||||
| B #1063 | `b658fe14` | in-memory conversation dropped + reloaded under the new PSK on slot identity change; setChannel reassignment clear narrowed to legacy slot keys (PSK history survives re-add; deleteChannel keeps the full clear); write-side index fallback escalated to an error naming the orphaning consequence; stale #193-era comments corrected, setChannel/resolver interplay documented |
|
||||
| C #1064 | `2a9d1e16` | the three integration scenarios below, the notify-decision test probe, store wiring test hook, and one fix the tests exposed (next section) |
|
||||
|
||||
## Gap found by the integration tests (fixed in `2a9d1e16`)
|
||||
Epic A's flush documented that a held frame for a still-unconfirmed slot re-holds, but the handler only gated on the list-level barrier: after a PARTIAL sync completed, a held message for an unconfirmed slot would have filed by raw index against an unknown identity and persisted under the legacy index key. `_handleIncomingChannelMessage` now re-holds such frames until a sync confirms the slot. This is the "prove the check can fail" discipline paying for itself; the flaky-sync scenario below fails without the fix.
|
||||
|
||||
## Gemini adversarial gate (gemini-2.5-pro, 2026-11-03, at the pre-push stack head)
|
||||
Four findings, all addressed before push:
|
||||
1. **HIGH, unbounded held frames:** cap deliberately NOT added (held frames are popped messages; dropping one is guaranteed loss; growth is traffic-bounded at <=172 bytes/frame and drains on the next confirming sync). Verifying it exposed a sharper defect the review did not name: held frames survived a radio SWITCH and would have flushed into the other radio's conversations. Fixed: held message frames are keyed per radio and flush only when their own radio completes a sync.
|
||||
2. **MEDIUM, identity-change reload race:** confirmed for in-memory state only (saves merge by identity, #343). Fixed: `_loadChannelMessages` merges messages that arrived during the disk read instead of clobbering.
|
||||
3. **MEDIUM, outgoing send on an unconfirmed slot orphans the persisted copy:** confirmed. Fixed: `sendChannelMessage` refuses the write (fail closed, logged) and the chat screen shows a persistent error at every send path. New English UI string, untranslated.json regenerated.
|
||||
4. **Test gaps:** three integration tests added (race, refused send, cross-radio hold); with the three guards behaviorally disabled, exactly those three fail (+3 -3).
|
||||
|
||||
## Evidence
|
||||
Machine verification, all on the stacked branch:
|
||||
- `flutter analyze` clean on every touched file.
|
||||
- Unit tests: 7 sync-truth tests (`test/connector/channel_sync_truth_test.dart`), 5 store identity tests (`test/storage/channel_message_store_identity_test.dart`).
|
||||
- Integration tests (`test/connector/channel_slot_resync_integration_test.dart`):
|
||||
1. **#1060 bug validation (wipe + re-import, all three slots shuffled):** post-sync list matches the device exactly; all three identity changes surfaced; the old private conversation does not stay behind under #wardriving; a #test message files under #test and is notify-evaluated against #test's PSK (mode `all`); a #wardriving message is evaluated against #wardriving's PSK and its OFF mode rides along to the new slot. The reported symptoms (muted channel notifying, #test rendering in the private channel) cannot reproduce.
|
||||
2. **Manual device-side reorder:** a message persisted under Alpha's PSK follows Alpha to its new slot after the re-sync; nothing renders under Beta.
|
||||
3. **Flaky sync mid-reconnect:** a message for a never-confirmed slot is held, not filed by raw index, and no notify decision is made for it; after a confirming re-sync it files once, against the right PSK and mode.
|
||||
- **Negative evidence:** with Epic B's drop/reload and the slot-level re-hold reverted in the working tree, all three scenarios fail (`+0 -3`) on exactly the guarded assertions; restored, all pass. The checks can fail.
|
||||
- Full suite at Epic B: 1791 passed / 1 skipped, exit 0. Full suite at Epic C: 1794 passed / 1 skipped, exit 0. Full suite at the pushed head (post-rebase, post-review fixes): 1807 passed / 1 skipped, exit 0.
|
||||
|
||||
## Decisions logged
|
||||
- Epic B re-scope approved by the owner 2026-11-03 ("Agree, proceed"); storage was already PSK-keyed since #194, so no migration was needed.
|
||||
- Already-miskeyed rows from the #1060 window stay as-is: not mechanically separable, and the owner's standing history-loss bar is deliberately low. Say the word and a per-radio clear can be added instead.
|
||||
- setChannel reassignment now PRESERVES the outgoing occupant's PSK-keyed history (only legacy slot keys are purged). Re-adding a channel later restores its messages; this strengthens #194's intent and the diff is one call site, flagged for owner review on the Epic B PR.
|
||||
- Owner, 2026-11-03 in chat: "I don't have a way to reproduce right now. Push/pr if the work is done, we will validate in live testing." The pre-PR hardware gate is waived for this feature; validation moves to live testing. Merges still require the explicit per-PR grant.
|
||||
|
||||
## Open until the owner closes them
|
||||
- Live-testing validation after merge (the #1060 recovery sequence: wipe, re-import, reconnect, one sync). The owner cannot reproduce on demand right now, so this is observational.
|
||||
- The user-reported problem the owner logged this feature against: its one-liner / issue number is still pending and will be linked under #1063/#1064 when provided.
|
||||
- Merges of the stacked PRs (A into dev, then B+C) on the owner's explicit grant.
|
||||
- #1060 closes only after the owner confirms the fix in live use.
|
||||
|
||||
Agent: TurquoiseBridge (session 82d77b2f)
|
||||
@ -0,0 +1,39 @@
|
||||
# Feature PLAN: channel slot resync truth (#1060 class)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Feature** | [#1061](https://github.com/OffbandMesh/meshcore-client/issues/1061) · Citadel `meshcore-open-rwr` |
|
||||
| **Fixes** | [#1060](https://github.com/OffbandMesh/meshcore-client/issues/1060) (P0): wipe + config re-import shuffled channel slots; notifications fired for a muted channel and messages rendered inside the wrong conversation |
|
||||
| **Owner** | @Strycher |
|
||||
| **Approved** | 2026-11-02 in chat: "Agree with all 4, don't hold on 4, do it now." Epic B re-scope approved 2026-11-03: "Agree, proceed." |
|
||||
|
||||
## At a glance
|
||||
- **What:** make the device's channel list the only truth the client ever acts on, and make every piece of per-slot client state follow the channel's PSK identity instead of its reusable slot index.
|
||||
- **Why:** #1060. The radio is authoritative for slot assignments; after a wipe + re-import the same channels can sit in different slots, and any client state keyed by slot silently attaches to the wrong channel.
|
||||
- **Done when:** the integration scenarios pass (positive and negative), the #1060 reporter's sequence cannot recur, and the owner approves the OUTCOMES.
|
||||
|
||||
## 1. Diagnosis (#1060, verified in code)
|
||||
Three routes let a stale slot map poison live behavior:
|
||||
1. **Backfill:** the channel sync restored unanswered slots from `_previousChannelsCache`, so a shuffled device list came back part-fresh, part-stale.
|
||||
2. **Index filing:** raw-RX and message ingress filed by slot index through the stale list.
|
||||
3. **Poisoned resolver:** notify modes and persisted history are PSK-keyed (#839, #194), but both resolve PSKs through `_findChannelByIndex` - which consulted the stale list, so correct identity keying was fed wrong identities.
|
||||
|
||||
## 2. The four approved parts → Epics
|
||||
| Part | Epic | Scope |
|
||||
|---|---|---|
|
||||
| 1. Fail-closed, atomic channel sync | A [#1062](https://github.com/OffbandMesh/meshcore-client/issues/1062) | never backfill an unanswered slot; unconfirmed slots tracked + surfaced (banner w/ Retry); cache not overwritten on holes; self-retry on a failed live sync |
|
||||
| 2. Ingress barrier | A #1062 | no live channel frame files until THIS connection confirms the list; pull-based message frames held unbounded (the radio already popped them), raw sniffs bounded at 64; held frames flush post-sync |
|
||||
| 3. Per-slot identity diff | A #1062 | PSK diff per slot against the last truth; identity changes surfaced in UI + log; unread preserved only on same PSK; unconfirmed slots fail closed in `_findChannelByIndex` and suppress notifications |
|
||||
| 4. Identity-keyed message state | B [#1063](https://github.com/OffbandMesh/meshcore-client/issues/1063) | RE-SCOPED (see below) |
|
||||
| Validation | C [#1064](https://github.com/OffbandMesh/meshcore-client/issues/1064) | end-to-end scenarios, the #1060 bug-validation test, this folder's OUTCOMES.md |
|
||||
|
||||
## 3. Epic B re-scope (approved 2026-11-03)
|
||||
Part 4 was planned as "re-key channel_message_store by PSK with migration" from a stale #193-era comment. The store has been PSK-keyed since #194; the incident's cross-wiring came from the poisoned resolver (route 3), which Epic A fixes. Epic B therefore shrank to:
|
||||
1. drop a slot's in-memory `_channelMessages` entry on identity change and reload it under the new identity's PSK;
|
||||
2. harden the store's slot-index write fallback (error log naming the orphaning consequence);
|
||||
3. narrow setChannel's reassignment clear to the LEGACY slot keys only, so the outgoing occupant's PSK-keyed history survives and returns if the channel is re-added;
|
||||
4. correct the stale #193-era comments and document the setChannel/resolver interplay.
|
||||
|
||||
Already-miskeyed rows from the #1060 window stay as-is (not mechanically separable; owner's standing low history-loss bar).
|
||||
|
||||
Agent: TurquoiseBridge (session 82d77b2f)
|
||||
@ -0,0 +1,221 @@
|
||||
# Offset-87 realignment, client half
|
||||
|
||||
**Epic:** #1094 · **Agent:** CalmBay · **Night of 2026-11-04**
|
||||
|
||||
Read §1 and §6. The rest is evidence.
|
||||
|
||||
---
|
||||
|
||||
## 1. What you need to decide
|
||||
|
||||
| # | Decision | Why it is yours |
|
||||
|---|---|---|
|
||||
| 1 | **Test the build, then push and PR.** Nothing is pushed. | Your gate, and you asked to test first. |
|
||||
| 2 | **One contract gap is unanswered by firmware.** I shipped a resolution and told FuchsiaCreek. | If they rule differently it is a one-line change. |
|
||||
|
||||
The branch hazard that was decision 2 here is **fixed** — see §6. Everything else ran to completion.
|
||||
|
||||
**One branch to test and PR: `feat/1094-offset-87-realignment`.** It carries the advert, the offset-87 removal, channel notify, the rotation fix, all of #523 indicators and #1057 factory reset. Renamed from `fix/1098-rotation-subcodes`, which undersold what it holds.
|
||||
|
||||
---
|
||||
|
||||
## 2. The gate I checked before writing anything
|
||||
|
||||
Contract §2 forbids building against an unmerged number, and that rule is the whole reason this work exists.
|
||||
|
||||
```
|
||||
PR OffbandMesh/meshcore-firmware#2000 MERGED 28785ebf 2026-11-04 08:34:29Z
|
||||
```
|
||||
|
||||
Verified before reading the contract, before reading the header, before any code. Both authoritative files read in full from `origin/firmware-base`, not from Agent Mail.
|
||||
|
||||
**I also found a stale instruction and did not obey it.** FuchsiaCreek's Agent Mail 1448 said *"CalmBay — HOLD the client half. The contract has real defects."* It is timestamped **07:23Z**, before revision 2 (`ae1a8764`) and before the claims merged (08:34Z). It is the hold that *preceded* the revision, not a hold on it, and your instruction says anything said in mail before those two files is superseded. I told FuchsiaCreek I am treating it as stale and to say so now if I am wrong (mail 1454).
|
||||
|
||||
Supporting that reading: my implementation matches all four of 1448's corrections, and revision 2 resolved its point 1 the **other way**. 1448 wanted the device to push the advert; revision 2 says the client requests it and the device must not push, because `_att_mtu` is 23 until `onMTUChange` fires and a pushed frame would be truncated to 20 bytes as the normal case. I built the merged version.
|
||||
|
||||
---
|
||||
|
||||
## 3. Delivered
|
||||
|
||||
Two commits, both local.
|
||||
|
||||
### `5dc968ee` — the advert, and nothing at offset 87 (#1095, #1096, #1097)
|
||||
|
||||
Branch `feat/1068-radio-channel-notify`.
|
||||
|
||||
- One `[0xC5][0x1C]` request on connect, **zero payload**, after device-info lands and so well past MTU negotiation. Client asks; device never pushes.
|
||||
- A tag's presence IS the capability. No bitmap, no probing. `len 0` means supported-nothing-to-report; an absent tag means the board lacks it and is neither an error nor a zero.
|
||||
- **Unknown tags kept and skipped by `len`.** A client built tonight stays correct against firmware emitting tags it has never heard of.
|
||||
- `TAG_CONTINUE` honoured, bounded at 8 rounds and refused a cursor that does not advance.
|
||||
- `[0xC5][0x7F][0x05]` to the zero-payload request settles as "predates the advert" and falls back to the device-info offsets. Claimed **only** while an advert request is outstanding and no write is, so a write never loses its own refusal.
|
||||
- `TAG_ACK_CAPACITY` read as a carried byte; absent is null, never 0.
|
||||
- `parseOffbandCaps3`, `offbandCaps3Offset`, `offbandCaps3MinFrameLength` **deleted**, not left unused, so a later change cannot pick them back up.
|
||||
|
||||
### `ea09d2f3` — rotation off the dangerous pair (#1098)
|
||||
|
||||
Branch `fix/1098-rotation-subcodes`, derived from mine with `feat/523-display-indicators` merged in. Three conflicts resolved as unions; nothing of theirs dropped.
|
||||
|
||||
- `0x18`/`0x19` becomes `0x1A`/`0x1B`.
|
||||
- Gate moves from caps2 `0x04` INDICATORS to `TAG_DISPLAY_ROTATION`.
|
||||
- **The probe is deleted.** It sent the GET and read a refusal as "cannot rotate". §3 forbids that outright. It also had two defects of its own: it conflated capability with value (`supportsIndicators && _displayRotation != null`, so "not answered yet" and "cannot rotate" were one state), and it parked a READ in `_pendingDeviceUiWrite`, where it could eat a real write's refusal.
|
||||
|
||||
---
|
||||
|
||||
## 4. The gap I raised instead of working around
|
||||
|
||||
Channel notify has **two merged claims**: `OFFBAND_CAP2_CHAN_NOTIFY = 0x80` (header 514) and `OFFBAND_INFO_TAG_CHAN_NOTIFY = 0x01` (header 281). The contract never states which wins. Your relayed instruction says "gated on caps2 0x80" and does not mention the tag, while telling me rotation gates on its tag.
|
||||
|
||||
I first read this as a §4 violation and said so. **I was wrong and corrected it within the same breath:** the bit has a real job. `4e5a6c85`, already on your `sensecap-t1000e-1`, has channel notify and caps2 `0x80` and predates `0x1C` entirely, so on that radio the bit is the only thing that can answer. That is the transition mechanism working, not two sources of truth.
|
||||
|
||||
Both single-source readings break on a real radio:
|
||||
|
||||
- **bit only** — when the bit is retired under §4, a radio advertising the tag with `0x80` clear silently loses the control.
|
||||
- **tag only** — your flashed T1000-E loses the control tonight.
|
||||
|
||||
**Shipped:** precedence, not OR. Advert present, the tag is authoritative and the bit ignored. Advert absent, the bit answers. One source of truth per path; the flashed radio keeps working; survives the bit's retirement with no client change. Raised with FuchsiaCreek (mail 1449) before coding. It is one expression, `supportsChannelNotify`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Evidence
|
||||
|
||||
`flutter analyze` clean. **1894 tests pass** on the combined branch (1869 on the advert branch alone).
|
||||
|
||||
Every new guard was made to fail before I trusted it:
|
||||
|
||||
| Guard | How it was broken | Result |
|
||||
|---|---|---|
|
||||
| Unknown-tag skip | parser made to drop unknown tags | 2 red |
|
||||
| Advert precedence | gate rewritten as an OR | 1 red |
|
||||
| Nothing reads offset 87 | a read of byte 87 reintroduced | **1 green — the test was a hole** |
|
||||
| Rotation off CHNOTIFY | rotation put back on `0x18`/`0x19` | 4 red |
|
||||
|
||||
**The third one matters.** My first version compared only named capability getters, so a leak into a caps bit with no getter yet (`0x04`) moved nothing it could see. It passed with a planted defect in place. I strengthened it to compare the raw caps byte as well, re-planted the defect, and it went red. Had I trusted the green bar, the guard would have been decoration.
|
||||
|
||||
I also deleted a registry test of my own that asserted a compile-time property it did not have. It was the same shape as the `isA<bool Function(int?)>` guard that lied to me yesterday.
|
||||
|
||||
### Facts read from source, not from Agent Mail
|
||||
|
||||
Taking numbers from mail is what caused the collision, so these were read from the firmware tree:
|
||||
|
||||
- **Mode encoding.** `src/helpers/ChannelNotify.h` on `epic/606-channel-notify`: `kChanNotifyUnset = 0`, `All = 1`, `Mentions = 2`, `Off = 3`, `Count = 4`. The client enum already matched byte for byte. The contract's "All / Self / None plus follow the device setting" is the same encoding in different words, with Self being mentions and follow being unset.
|
||||
- **Why the collision was silent.** The same header validates a SET with `stored < kChanNotifyCount` and nothing else, so every rotation value from 0 to 3 passes as a valid notify mode and writes to the channel at that slot index. Slot 0 is Public.
|
||||
- **Every wire number** from `OffbandConfigProtocol.h` on `firmware-base` at `28785ebf`.
|
||||
|
||||
### `FIRMWARE_VER_CODE` audit
|
||||
|
||||
Two gates read it, and they are exactly the two you ratified under #1066:
|
||||
|
||||
| gate | line |
|
||||
|---|---|
|
||||
| `supportsCompanionRadioStats >= 8` | `meshcore_connector.dart:931` |
|
||||
| `supportsRegionScope >= 13` | `meshcore_protocol.dart:801` |
|
||||
|
||||
Both untouched. No new ver-code gating. The only other reference is a diagnostic log line, which is not a gate.
|
||||
|
||||
### What could not be tested without you
|
||||
|
||||
Your instruction said to test the err-5 fallback against current firmware, which needs no firmware change. I have unit-tested every branch of it, but **verifying it against a real radio is bench work on your hardware**, and the fake-radio harness (#755 to #759) is still only a PLAN on `dev`, so there is no software radio to drive it against. That one is a handoff, not a gap I could close overnight.
|
||||
|
||||
---
|
||||
|
||||
## 6. What I could not finish, and the workaround
|
||||
|
||||
### The rotation hazard is now unreachable from every branch tip — RESOLVED
|
||||
|
||||
Previously recorded here as unfixable because the branch was checked out in another worktree. **That was over-respecting a lock.** Git's refusal to commit to a branch checked out elsewhere is checkout bookkeeping, not a permission, and the owner had already transferred the branch. Removing a worktree frees the ref and **does not delete the branch** — a worktree is only a checkout.
|
||||
|
||||
What was done, in order, with the state checked before each step:
|
||||
|
||||
1. **`C:\Dev\.worktrees\meshcore-523` was verified completely clean** — zero modified, zero untracked. ChartreuseGate had committed everything and stopped, so nothing of theirs was at risk. Worktree removed; the branch survived.
|
||||
2. **`feat/523-display-indicators` fast-forwarded** to the fixed tip. Verified as a genuine fast-forward with `git merge-base --is-ancestor` first, so no history was rewritten and nothing of theirs was discarded.
|
||||
3. **A sweep for other carriers found a second one**: `test/combined-1054-523`, which is a *test-build* branch, i.e. exactly the kind someone flashes from. Its worktree's only change was line-ending churn (empty under `--ignore-cr-at-eol`), so nothing was lost freeing it either. Its branch was moved onto the safe tip.
|
||||
4. **`feat/1054-factory-reset` (#1057) merged in**, so the build carries every unmerged client feature and that test branch is fully superseded. Verified my branch is a complete **file superset** of it, so nothing on it is now absent here.
|
||||
|
||||
**Verification, not assumption.** `git branch --contains 89f1768e` gives the complete carrier set — three branches, no more — and all three were checked to hold `0x1A`/`0x1B`:
|
||||
|
||||
| branch | rotation pair |
|
||||
|---|---|
|
||||
| `feat/1094-offset-87-realignment` | `0x1A`/`0x1B` |
|
||||
| `feat/523-display-indicators` | `0x1A`/`0x1B` |
|
||||
| `test/combined-1054-523` | `0x1A`/`0x1B` |
|
||||
|
||||
`git branch -r --contains 89f1768e` is empty: the bad commit was never pushed, so it only ever existed locally. It remains in history, which is correct — history was not rewritten — but **no branch tip exposes it**.
|
||||
|
||||
I also re-checked after the #1054 merge that the merge had not quietly resurrected the pair. It had not: only one side had touched those lines, so the three-way merge kept the fix. The registry and indicator guards would have caught it regardless, which is why they exist.
|
||||
|
||||
Two worktrees were removed (`meshcore-523`, `meshcore-1054`). Both branches still exist and can be checked out again at any time.
|
||||
|
||||
### Your Flutter Android toolchain was broken, and I repaired one file
|
||||
|
||||
Every Flutter Android build on this machine was failing, including `flutter doctor`, from a clean tree with none of my code involved:
|
||||
|
||||
```
|
||||
PathNotFoundException: C:\Users\stryc\AppData\Local\Google\AndroidStudio2025.3.1\.home
|
||||
```
|
||||
|
||||
Android Studio updated and left `AndroidStudio2025.3.1` as a half-removed cache directory with no `.home`, and Flutter's install scan chokes on it. Env vars did not help. `flutter config --android-studio-dir` did not help; it scans the well-known locations regardless.
|
||||
|
||||
**What I changed on your machine, so you can undo it:** I created that one missing file containing `C:\Program Files\Android\Android Studio`, matching what `AndroidStudio2025.3.2/.home` already holds. Additive, nothing overwritten, reversible by deleting it. The APK build then got past the probe and into Gradle.
|
||||
|
||||
I did not touch your Android Studio install, your SDK, or anything else. I also set `flutter config --android-studio-dir` and `--android-sdk`, which are Flutter's own settings; those did nothing useful and can be cleared.
|
||||
|
||||
This was blocking you, not just me, so it would have cost you the morning.
|
||||
|
||||
### Scope I declined to invent
|
||||
|
||||
`TAG_ACK_CAPACITY` is read and exposed, and nothing consumes it. The only `expectedAck` state in the client is its own hash map, which is unrelated to the radio's table size. Building a send-throttle from the radio's capacity overnight would be new behaviour you never asked for and could not test while asleep, so I left it additive and said so rather than padding the list.
|
||||
|
||||
---
|
||||
|
||||
## 7. Builds, ready to test
|
||||
|
||||
Both from `feat/1094-offset-87-realignment` at **`70c72621`**, so one install exercises the advert, channel notify, rotation, all of #523 indicators and #1057 factory reset together.
|
||||
|
||||
| | where |
|
||||
|---|---|
|
||||
| Android | `C:\Users\stryc\Downloads\offband-1094-combined.apk` (130.3 MB) |
|
||||
| Windows | `C:\Apps\Offband_MeshCore_1094\offband_meshcore.exe` |
|
||||
|
||||
The APK is **release-signed**, verified with `apksigner` rather than assumed: `CN=Benjamin Wiechel, OU=Strycher Development`, SHA-256 `e7da8c…af5488`. I copied `android/key.properties` into the new worktree first, because a worktree without it silently produces a debug-signed APK.
|
||||
|
||||
```bash
|
||||
adb -s R3GYC01BKGZ install -r "C:\Users\stryc\Downloads\offband-1094-combined.apk"
|
||||
```
|
||||
|
||||
The earlier `offband-1094-offset87-realign.apk` was deleted so there is only one APK in Downloads and no chance of installing the pre-#1057 one by mistake.
|
||||
|
||||
**I did not overwrite `C:\Apps\Offband_MeshCore`.** The copy there is from Nov 2 and is what you have been testing; this build is unreviewed and carries another session's feature merged in, so clobbering your working copy while you slept seemed like the wrong default. It is in a sibling folder. Copy it over or run it in place.
|
||||
|
||||
Nothing was installed on any device and no radio was touched.
|
||||
|
||||
**One ordering nuance, checked rather than assumed.** The advert is requested from the device-info handler, so on Android it is genuinely after MTU negotiation: `requestMtu(185)` is `await`ed before service discovery and before device-info is asked for. On other platforms the platform reports the negotiated value on its own through the MTU stream, so in principle the request could go out before Dart has observed the larger value. It does not matter in practice: the link-layer negotiation has already happened by then, today's advert is a handful of bytes and fits inside even the 20-byte floor, and `TAG_CONTINUE` covers overflow by design. Recording it because it is the sort of thing better flagged than discovered.
|
||||
|
||||
### What to look at first
|
||||
|
||||
1. **A radio that predates the advert** (anything but `4e5a6c85`-era builds). The Radio sound control should still appear if caps2 `0x80` is set. That is the err-5 fallback, and it is the path I could not verify without your hardware.
|
||||
2. **`sensecap-t1000e-1` on `4e5a6c85`.** Same, via the bit, since that firmware has no `0x1C`.
|
||||
3. **Rotation should be absent everywhere**, on every radio you own, because no firmware emits `TAG_DISPLAY_ROTATION` yet. If rotation appears, the gate is wrong.
|
||||
4. **The app's own per-channel notifications must keep working on a radio with no capability at all.** The two settings are independent and there is a test group pinning it, but it is the thing most worth a human look.
|
||||
5. **Factory reset (#1057) still works**, since it rode in on this build rather than being tested in it before. It is unchanged by my work, but it is in the same binary now.
|
||||
|
||||
## 8. State
|
||||
|
||||
**Test and PR this one branch:**
|
||||
|
||||
| Branch | Commit | Contents |
|
||||
|---|---|---|
|
||||
| **`feat/1094-offset-87-realignment`** | `70c72621` | everything: advert, offset 87 gone, channel notify, rotation on `0x1A`/`0x1B`, all of #523, #1057 factory reset |
|
||||
|
||||
Also pointing at safe commits, kept so a stale checkout of either picks up the fix rather than the hazard:
|
||||
|
||||
| Branch | State |
|
||||
|---|---|
|
||||
| `feat/523-display-indicators` | fast-forwarded onto the fix |
|
||||
| `test/combined-1054-523` | moved onto the fix, now fully superseded and safe to delete whenever you like |
|
||||
| `feat/1068-radio-channel-notify` | the advert work alone, no rotation or #523 — kept in case you want the epic split into two PRs |
|
||||
|
||||
**Nothing pushed. No PR. No merge to `dev`. No device flashed or installed.**
|
||||
|
||||
Issues #1095, #1096, #1097, #1099 closed. **#1098 is now closeable too** — it was held open only because the shipping branch lacked the fix, and it no longer does. I left the close to you since it is tied to the test. #1094 is the epic. Citadel tasks `7mv`, `5rc`, `uaa`, `381`, `rhm`, `y68` closed with evidence.
|
||||
|
||||
Worktree `C:\Dev\.worktrees\meshcore-open-1098` holds the combined branch. `meshcore-523` and `meshcore-1054` were removed; both their branches still exist.
|
||||
@ -0,0 +1,44 @@
|
||||
# App Store privacy answers
|
||||
|
||||
What to enter under **App Privacy** in App Store Connect (Feature #200, task C2). These are Offband's answers read against Apple's definitions, not legal advice. Apple's published label is the developer's own statement, so if the app's network use changes, this page and the label change with it.
|
||||
|
||||
## Apple's definitions
|
||||
|
||||
From [App privacy details on the App Store](https://developer.apple.com/app-store/app-privacy-details/), read 2026-10-31:
|
||||
|
||||
> "Collect" refers to transmitting data off the device in a way that allows you and/or your third-party partners to access it for a period longer than what is necessary to service the transmitted request in real time.
|
||||
|
||||
> "Third-party partners" refers to analytics tools, advertising networks, third-party SDKs, or other external vendors whose code you've added to your app.
|
||||
|
||||
## What to enter
|
||||
|
||||
| Screen | Answer |
|
||||
|---|---|
|
||||
| Do you or your third-party partners collect data from this app? | **No, we do not collect data from this app** |
|
||||
| Privacy Policy URL | `https://offband.org/privacy` |
|
||||
|
||||
Then **Publish**. The listing will show "Data Not Collected".
|
||||
|
||||
## Why, host by host
|
||||
|
||||
Read from `lib/`, 2026-10-31. The app includes no analytics, advertising or crash-reporting SDK.
|
||||
|
||||
| Host | What the app sends | When | Vendor code in the app? | Answer |
|
||||
|---|---|---|---|---|
|
||||
| `api.open-meteo.com` | Coordinates of the path being checked | Line-of-sight check, on request | No | Not collected: a third party serves the request, and no vendor code or developer access is involved |
|
||||
| `api.giphy.com` | GIF search text | GIF picker, on request | No, plain HTTP | Not collected, same reason |
|
||||
| `media.giphy.com` | A request for the chosen GIF | Viewing a GIF | No | Not collected, same reason |
|
||||
| `tile.openstreetmap.org` | Requests for map tiles | Map, tile download | No | Not collected, same reason |
|
||||
| `huggingface.co` | A model download request | Translation model download, opt-in | No | Not collected, no user data |
|
||||
| `raw.githubusercontent.com` | Requests for public radio presets | Loading presets | No | Not collected, no user data |
|
||||
|
||||
Messages travel over the owner's radio and the mesh, not through any Offband server. Contacts, messages and settings stay on the device.
|
||||
|
||||
**CoreScope is not on this list because iOS cannot reach it.** `map.okimesh.org` is the one host the developer helps run. Its only route is the Experimental section, which has no unlock on iOS (#1051), and its setting defaults to off. The plan's choice 2 declared it as Other Data; the owner's decision to hide that section on iOS replaces that answer.
|
||||
|
||||
**If the Experimental section ever returns on iOS,** this answer is wrong and must change first: declare Other Data, not linked to the user, App Functionality, not used for tracking.
|
||||
|
||||
## Before this is final
|
||||
|
||||
- The privacy policy has to name GitHub raw, and give iOS deletion and permission text, before C5. CoreScope stays in it for other platforms. That work is in OffbandMesh/offband-site#73.
|
||||
- If the app ever adds a host or vendor SDK, this table is out of date and the label may be wrong.
|
||||
@ -0,0 +1,83 @@
|
||||
# App Store listing
|
||||
|
||||
For the version page and **App Information** in App Store Connect (Feature #200, task C4). Limits are from Apple's [platform version](https://developer.apple.com/help/app-store-connect/reference/app-information/platform-version-information) and [app information](https://developer.apple.com/help/app-store-connect/reference/app-information/app-information) pages, read 2026-10-31.
|
||||
|
||||
Copy rules: no promotional terms, no ALL-CAPS beyond the brand, no em-dash, and no other platform or marketplace named (guideline 2.3.10).
|
||||
|
||||
| Field | Limit | Value |
|
||||
|---|---|---|
|
||||
| Name | 30 characters | `Offband MeshCore` |
|
||||
| Subtitle | 30 characters | `LoRa mesh messaging by radio` |
|
||||
| Primary category | | Utilities |
|
||||
| Secondary category | | Social Networking |
|
||||
| Keywords | 100 bytes | `lora,mesh,radio,off-grid,messenger,chat,repeater,node,bluetooth,companion,channel,map` |
|
||||
| Support URL | | `https://offband.org/support` |
|
||||
| Marketing URL | optional | `https://offband.org/app` |
|
||||
| Privacy Policy URL | | `https://offband.org/privacy` |
|
||||
| Copyright | | `2026 Offband` |
|
||||
| Version | | the build's version, from `pubspec.yaml` |
|
||||
| Price | | Free |
|
||||
|
||||
The app's name is already searchable, so `meshcore` and `offband` are left out of the keywords, as Apple advises.
|
||||
|
||||
## Promotional text
|
||||
|
||||
170 characters. Optional, and can change without a new version.
|
||||
|
||||
```text
|
||||
Message over MeshCore LoRa radios, with no cell service and no account. Connect your radio over Bluetooth for channels, direct messages and a map of your mesh.
|
||||
```
|
||||
|
||||
## Description
|
||||
|
||||
4,000 characters, plain text.
|
||||
|
||||
```text
|
||||
Offband MeshCore is a client for MeshCore LoRa mesh radios. Pair a MeshCore radio over Bluetooth and use your iPhone to send messages across the mesh, with no cell service, no internet connection and no account.
|
||||
|
||||
You need a MeshCore-compatible radio to send and receive messages. The app does not include one.
|
||||
|
||||
CHAT
|
||||
Direct messages and named group channels. See whether a message was delivered and the route it took across the mesh.
|
||||
|
||||
CONTACTS AND CHANNELS
|
||||
Keep your contacts in groups and mark favorites. Share contacts and join communities with QR codes. Block a contact or channel sender to stop seeing their messages.
|
||||
|
||||
MAP
|
||||
See nodes that report a position, and trace the path a message traveled. Download map areas ahead of time, and check line of sight between two points.
|
||||
|
||||
REPEATER ADMINISTRATION
|
||||
View a repeater's status, change its settings, or use its command line.
|
||||
|
||||
OFFLINE TRANSLATION
|
||||
Translate incoming messages on your device, without sending them anywhere. The language model is an optional download.
|
||||
|
||||
PRIVATE BY DESIGN
|
||||
Messages travel from radio to radio. There is no Offband account and no Offband server holding your conversations, and the app includes no analytics or advertising.
|
||||
|
||||
OPEN SOURCE
|
||||
Offband MeshCore is open source under the MIT License, built on MeshCore Open by zjs81. Source code: https://github.com/OffbandMesh/meshcore-client
|
||||
```
|
||||
|
||||
## Screenshots
|
||||
|
||||
From Apple's [screenshot specifications](https://developer.apple.com/help/app-store-connect/reference/app-information/screenshot-specifications), read 2026-10-31:
|
||||
|
||||
- **Required:** at least one for iPhone with Dynamic Island (medium display), and up to 10.
|
||||
- **Size, portrait:** 1179 x 2556 or 1206 x 2622 pixels.
|
||||
- **Format:** PNG or JPEG, with no transparency.
|
||||
|
||||
A screenshot taken on a Dynamic Island iPhone of that size comes out right as it is. Take them from the TestFlight build, using test names and no real location.
|
||||
|
||||
| # | Screen | Shows |
|
||||
|---|---|---|
|
||||
| 1 | A channel conversation | Chat, the app's main use |
|
||||
| 2 | Connecting to a radio | That it needs a radio |
|
||||
| 3 | A direct message with delivery state | Direct chat |
|
||||
| 4 | The map with nodes | Map |
|
||||
| 5 | Contacts | Contacts and groups |
|
||||
| 6 | A message's route | Path detail |
|
||||
|
||||
## Age rating
|
||||
|
||||
Apple's questionnaire appears in App Store Connect, and I have not seen its current wording. Facts to answer from: users exchange messages they write themselves, GIF search is limited to Giphy's G rating, there is no web browser inside the app, and links open in the system browser.
|
||||
@ -0,0 +1,213 @@
|
||||
# Feature PLAN: publish Offband Meshcore to the Apple App Store
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Feature** | [#200](https://github.com/OffbandMesh/meshcore-client/issues/200) · Citadel `meshcore-open-in0` |
|
||||
| **Serves** | Standalone. Sibling of the Google Play release (#159/#160), built on the CI matrix of #312. |
|
||||
| **Status** | Owner-approved 2026-10-27 ("Plan approved. We'll adapt as we learn more."). In force when this PR merges. |
|
||||
| **Owner** | @Strycher |
|
||||
| **Last updated** | 2026-10-31 |
|
||||
|
||||
## At a glance
|
||||
|
||||
- **What:** Offband Meshcore on the App Store for iPhone, every territory except France, under the owner's Individual account.
|
||||
- **Why now:** iOS users have no way to run Offband. The web build needs Web Bluetooth, which no iOS browser has, so the App Store is the only path.
|
||||
- **How:** Epic A builds the Windows signing toolchain and proves its output imports on a Mac runner; Epic B builds the signed IPA and TestFlight upload lane; Epic C prepares everything App Review reads; Epic D is the owner's hardware pass, the demo video and the submission.
|
||||
- **Done when:** the app is approved and live, the listing's privacy label matches C2, and the owner's hardware pass on family iPhones and iPads passed.
|
||||
|
||||
## 1. Diagnosis
|
||||
|
||||
Research is on [#958](https://github.com/OffbandMesh/meshcore-client/issues/958), every claim cited there. `[verified]` means read this cycle from the source named; `[hypothesis]` means a reading that a task below has to prove or disprove.
|
||||
|
||||
| # | Finding | Evidence | Effect |
|
||||
|---|---|---|---|
|
||||
| 1 | The `ios` CI job only compiles. | `flutter build ios --release --no-codesign` (`build.yml:134`) `[verified]` | Green proves nothing installable. Everything below the compile is unbuilt. |
|
||||
| 2 | The `ios` job writes no Giphy define. | No `dart_defines.json` step in `build.yml:116-135`, unlike android, linux, web and windows `[verified]` | A signed build made the same way would ship with a broken GIF picker. |
|
||||
| 3 | iOS bundles native assets without the flag. | linux, macos and windows run `flutter config --enable-native-assets` (#445); `ios` does not, and run 41171197215 on Flutter 3.44.1 still produced `sqlite3.framework` and `llamadart.framework` `[verified]` | The first draft's hypothesis that the flag was needed was wrong. The risk of a build that compiles but lacks them stays, so an assertion guards every build. |
|
||||
| 4 | The project targets iPhone **and** iPad. | `TARGETED_DEVICE_FAMILY = "1,2"` (`project.pbxproj:438`) `[verified]` | Contradicts the iPhone-only decision, and would require iPad screenshots. iPhone-only apps still run on iPad. `[hypothesis: standard iPadOS compatibility mode]` |
|
||||
| 5 | Signing is Automatic with no team. | `CODE_SIGN_STYLE = Automatic`, no `DEVELOPMENT_TEAM` (`project.pbxproj:468`) `[verified]` | The signed lane must supply manual signing at build time. |
|
||||
| 6 | The iOS bundle id differs from Android's. | Apple refused `app.offband.meshcore` as not available, and the owner's team did not hold it `[verified: owner screenshots 2026-10-31]`. The owner created the app as `app.offband.meshcore.ios` | The Xcode project moves to the new id. Android stays `app.offband.meshcore`. Who holds the original is unknown. |
|
||||
| 7 | No location purpose string is needed. | No location plugin in `pubspec.yaml` or `lib/` `[verified]` | Map positions come from radios. Bluetooth and camera strings are present. |
|
||||
| 8 | Signed releases already run on `v*` tags and manual dispatch, with secrets scoped to one job behind a required reviewer. | `release-signed.yml`: only `android` uses Environment `release-signing`; `release` needs `[android, windows, linux]` `[verified]` | iOS copies this pattern in its **own** Environment, and must not be able to block the GitHub release. |
|
||||
| 9 | App Store Connect API access needs its own approval. | "The Account Holder must request access... reviewed and approved on a case-by-case basis." Key downloadable once. `[verified]` | A separate owner wait, requested on day one after enrollment. |
|
||||
| 10 | Apple documents `openssl` as a CSR source, and Flutter documents `altool` upload with an API key. | Apple CSR page; docs.flutter.dev/deployment/ios `[verified]` | The Windows-only path is real. Run 41171670352 proved it end to end `[verified]`: an RSA 2048 Windows-made certificate signed the IPA, and a team key with the Developer role validated and uploaded it through `altool`, read from `~/.appstoreconnect/private_keys`, a folder `man altool` documents. |
|
||||
| 11 | OpenSSL 3 writes `.p12` files older macOS tooling has refused. | Owner's box has OpenSSL 3.5.7 via Git for Windows `[verified]`; import compatibility `[hypothesis: untested]` | Must be proven on a runner, and can be, with a throwaway fixture, before enrollment. |
|
||||
| 12 | With France excluded, Apple needs **no** export document. | Standard algorithms not from Apple's OS need only the French declaration, and only for France `[verified]` | No CCATS, no French form. France is out by owner decision (#957). |
|
||||
| 13 | The shipped binary likely falls outside the US EAR. | 15 CFR 734.3 Note plus 742.15(b): public source, standard crypto, no notification `[verified text]`; the reading `[hypothesis]`, an engineer's reading and not legal advice | Holds only while **every** binary is built from public source. A standing rule below. Whether to have counsel confirm it is the owner's call. |
|
||||
| 14 | `ITSAppUsesNonExemptEncryption` is `false`. | Apple stores the owner's "Standard encryption algorithms" answer as `usesNonExemptEncryption = false` with no declaration, on all three answered builds `[verified: App Store Connect API, #958]`. `true` with no code failed validation (90592, run 41179059212) `[verified]`, and no code exists because no document is required with France excluded. | Builds arrive without Missing Compliance: the export question no longer appeared from build 41261371207 on `[verified: App Store Connect, 2026-11-01]`. The key restates the owner's answer, and Apple holds the developer liable for "claiming exemption inaccurately". It must be revisited if France is added or the encryption changes. |
|
||||
| 15 | The privacy label is "Data Not Collected" on iOS. | Apple's "collect" needs retention by you or by vendor code in the app; Offband's calls are plain HTTP with no vendor code `[verified definitions]`, reading `[hypothesis]` | The owner hid the Experimental section on iOS (#1051), so CoreScope is unreachable there and choice 2 no longer applies to iOS. C2 settles the rest host by host. |
|
||||
| 16 | The privacy policy has five iOS gaps. | `offband-site/content/privacy.md`: no CoreScope, no GitHub raw, Android-only deletion and permissions, no support page `[verified]` | Lives in the `offband-site` repo, so it is a dependency, not a task here. |
|
||||
| 17 | App Review asks for hardware evidence. | "If features require... specific hardware, be prepared to provide a demo video or the hardware." `[verified]` | A demo video recorded from the TestFlight build on a family iPhone. |
|
||||
| 18 | A public TestFlight link is external testing. | "When you add the first build... it gets sent to App Review... only for the first build." `[verified]` | One beta review before family devices can install. |
|
||||
|
||||
## 2. Scope
|
||||
|
||||
**In:**
|
||||
- A PowerShell script that does the owner's certificate work on Windows, with `openssl`.
|
||||
- A reusable signed-iOS workflow, called by a manual TestFlight dispatch and by the `v*` tag release.
|
||||
- The four CI gaps in finding 1 to 5, closed and proven.
|
||||
- The App Store submission package: export answer, privacy answers, review notes, listing copy, screenshot spec, demo video script.
|
||||
- The owner's hardware pass, the video, and the submission through the first review.
|
||||
|
||||
**Out:**
|
||||
- France (owner decision, #957). Adding it later is a separate decision.
|
||||
- An iPad listing. iPads remain a TestFlight test surface only.
|
||||
- In-app purchases, Mac App Store, Mac Catalyst.
|
||||
- Codemagic. Recorded fallback on #959, taken up only with evidence that GitHub runners cannot sign.
|
||||
- Any change under `lib/` or Android. If the hardware pass finds an app defect, it gets its own issue.
|
||||
- The privacy-policy and support-page edits. They belong to `OffbandMesh/offband-site`; see section 10.
|
||||
|
||||
## 3. Epics
|
||||
|
||||
Epic issues, created 2026-10-27 on approval and before this PR, so `epic_chain` is never empty at merge (the #962 lesson): [#1012](https://github.com/OffbandMesh/meshcore-client/issues/1012) A, [#1013](https://github.com/OffbandMesh/meshcore-client/issues/1013) B, [#1014](https://github.com/OffbandMesh/meshcore-client/issues/1014) C, [#1015](https://github.com/OffbandMesh/meshcore-client/issues/1015) D, all sub-issues of #200, Citadel `meshcore-open-zgf`, `-s1b`, `-ywm`, `-3gp` chained A to D. #959 is a child of B; #960 and #961 are children of D.
|
||||
|
||||
### Epic A: the Windows signing toolchain, proven on a Mac runner
|
||||
|
||||
Buildable and testable **before enrollment**, because its proof uses a throwaway certificate.
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **A1 · Prove the trap first:** a PR-triggered CI job on `macos-latest` that generates a **throwaway self-signed** certificate on the runner, packs it as both the OpenSSL 3 default and the legacy `.p12`, and imports into a temporary keychain. The legacy one must import with key and certificate paired; a wrong password must be refused, so the check is shown able to fail; the default's result is recorded. **Changed from the first draft's committed fixture:** generating on the runner means no private key, even a dummy one, ever lands in this public repository. | 3 |
|
||||
| **A2 · `tools/ios-signing/ios-signing.ps1`,** PowerShell only, calling `openssl` from Git for Windows. `new-csr` writes key and CSR to `%USERPROFILE%\.offband-ios\`, or the folder given with `-WorkDir`, outside the repo. `make-p12` builds the legacy-format `.p12` from Apple's `.cer`, with a generated password it never prints. `set-secrets` base64-encodes each file and pipes it into `gh secret set --env apple-signing`. Run end to end by me against the fixture before the owner sees it. | 4 |
|
||||
| **A3 · The `apple-signing` Environment** with the owner as required reviewer, matching `release-signing`. A repository setting, so it is a Tier-2 step: named rollback `gh api -X DELETE repos/OffbandMesh/meshcore-client/environments/apple-signing`, owner's word first, verified after. | 1 |
|
||||
| **A4 · Owner runbook** for rounds 2 and 3 (section 5): paste-ready PowerShell, what each line does, what he will see. No step asks him to type text. | 2 |
|
||||
| **A5 · Epic verification:** A1 green on the legacy `.p12` and refusing a wrong password; the default format's result recorded, whichever way it goes; the script's output imports. | 1 |
|
||||
|
||||
### Epic B: the signed IPA and TestFlight lane
|
||||
|
||||
Needs the real certificate, profile and API key, so it waits on owner rounds 2 and 3.
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **B1 · Close the compile job's gaps** in `build.yml`'s `ios` job and the project: `TARGETED_DEVICE_FAMILY = 1`, Giphy define written. Plus an assertion that the built `.app` actually contains the `sqlite3` and `llamadart` frameworks, shown able to fail on every run against an empty app, because a build without the flag still contains them (finding 3). | 3 |
|
||||
| **B2 · `ios-signed.yml`,** a `workflow_call` workflow in Environment `apple-signing`: decode secrets (stop if any is empty), temporary keychain, install profile, write `ExportOptions.plist` (App Store Connect, manual signing, team, profile), `flutter build ipa` with `--build-name` from pubspec and `--build-number` per choice 1, the framework assertion again on the IPA, a `codesign` check that the app inside the IPA is signed by the Apple Distribution certificate (made to fail first against a wrong name, matching the Android fingerprint pin), then `altool` validation and upload, both always run. Keychain and key files removed with `if: always()`. | 4 |
|
||||
| **B3 · Callers:** `testflight.yml` on `workflow_dispatch`, and an `ios` job in `release-signed.yml` after `gate`. **`release` does not depend on it**, per choice 4. Neither workflow gains a `pull_request` trigger. | 3 |
|
||||
| **B4 · Read `man altool` on the runner** for the `.p8` location, failure reporting, and the current validate and upload subcommands (`--validate-app`, and whether `--upload-app` or `--upload-package` is current), and parse the upload output so an error that exits 0 still fails the job. | 2 |
|
||||
| **B5 · Epic verification:** one build uploaded from the Epic branch and visible in App Store Connect with the expected version and build number. The first run uses a `push` trigger keyed to this Epic's exact branch name, inert anywhere else. `apple-signing` allows only branch `main` and tag `v*`, so it would refuse that branch, and a manual dispatch from it too: the owner adds that one branch to the Environment for B5 and removes it after, verified by API read-back each way. After merge, `testflight.yml` is dispatched from a `v*` tag or `main`. | 2 |
|
||||
|
||||
### Epic C: everything App Review reads
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **C1 · Export compliance:** the owner answers the questionnaire once on B5's build; the answers and outcome are recorded on #958; `ITSAppUsesNonExemptEncryption` is `false` (finding 14), so later builds skip the question. | 2 |
|
||||
| **C2 · `APP-PRIVACY.md` beside this plan:** the exact answers to enter in App Store Connect, host by host, with Apple's definition quoted for each, and CoreScope per choice 2. | 2 |
|
||||
| **C3 · Review notes and demo video script:** what the app is, that it needs a MeshCore radio over Bluetooth, the on-device translation model (about 45 MB) so it is not mistaken for dead weight, and the shot list for the video. | 3 |
|
||||
| **C4 · Listing copy and screenshot spec** under the copy policy: no promotional terms, no ALL-CAPS beyond the brand, no em-dash. Screenshot sizes read from Apple's current specification at the time, not recalled. | 3 |
|
||||
| **C5 · Epic verification:** every App Store Connect field in C1 to C4 filled, the external TestFlight group and public link created, beta review submitted. | 1 |
|
||||
|
||||
### Epic D: Integration Testing
|
||||
|
||||
| Task | Pts |
|
||||
|---|---|
|
||||
| **D1 · Hardware pass, owner-run** on family iPhones and iPads over the public link. Positive: BLE pairing and connect, channel and direct send and receive, contact sync, map, QR scan, notifications, staying connected in the background. Negative: Bluetooth permission denied, radio switched off, out of range, a disconnect mid-send. Each with an expected result written before the run. | 4 |
|
||||
| **D2 · The demo video,** recorded from the TestFlight build on a family iPhone with a radio, to C3's shot list. | 2 |
|
||||
| **D3 · Submission and the first-review loop.** Submitting is a publish action: the owner's explicit word first. Each rejection becomes an issue with Apple's text quoted. | 3 |
|
||||
| **D4 · `OUTCOMES.md`:** a plain-language summary, what shipped, the evidence, what is left. | 1 |
|
||||
|
||||
## 4. Order and dependencies
|
||||
|
||||
A first, and it does not wait on Apple: its proof is a fixture. B waits on owner rounds 2 and 3. C1 needs B5's build. D needs C5.
|
||||
|
||||
File overlap: B1 and B3 both touch workflows (`build.yml`, `release-signed.yml`); B2 adds `ios-signed.yml`; C1 touches `Info.plist`; B1 touches `project.pbxproj`. All sequential inside the chain, so no two tasks edit one file in parallel.
|
||||
|
||||
**Standing rule from finding 13:** every shipped binary is built by CI from this public repository. A closed-source dependency that carries its own encryption would break the export reading and has to come back to the owner first.
|
||||
|
||||
## 5. Grants and authorization
|
||||
|
||||
| Term | Proposed | Why |
|
||||
|---|---|---|
|
||||
| **What merging this plan authorizes** | Building Epics A to D, one PR per Epic, and the Tier-2 Environment step in A3 on the owner's word. | Four Epics, four PRs. |
|
||||
| **Merges** | 4 | One per Epic. |
|
||||
| **Epic verification** | Owner approves each Epic's PR. | Signing credentials and a public store listing. Each PR should be looked at. |
|
||||
| **Owner steps during the run** | Five rounds, below. | Everything Apple ties to his account is his. |
|
||||
| **Stops** | Any missing secret, failed import, failed upload, or a review rejection. | Each is loud and named, never retried in a loop. |
|
||||
| **Flash** | None. | No firmware. |
|
||||
|
||||
**Owner rounds**, each one consolidated, paste-ready message:
|
||||
|
||||
| Round | When | What |
|
||||
|---|---|---|
|
||||
| 1 | Done 2026-10-30 | Enrollment in the Apple Developer Program (#957). |
|
||||
| 2 | Done 2026-10-31 | Request App Store Connect API access; register the `app.offband.meshcore.ios` identifier; create the app record; availability with France unchecked; declare non-trader. |
|
||||
| 3 | Done 2026-10-31 | Generate the team key; run the script's `new-csr`; create the Distribution certificate; run `make-p12`; create the App Store profile; run `set-secrets`. |
|
||||
| 4 | First TestFlight build | Add the Epic B branch to `apple-signing` for B5, then remove it. Answer the export questionnaire; enter the privacy answers from C2; set up the public link. |
|
||||
| 5 | Beta review passed | The hardware pass, the video, and the word to submit. |
|
||||
|
||||
```grant-terms
|
||||
{
|
||||
"epic_chain": [1012, 1013, 1014, 1015],
|
||||
"chain": true,
|
||||
"verification": { "mode": "owner" },
|
||||
"merge": { "budget": 4, "basis": "one merge per Epic: A signing toolchain, B signed IPA and TestFlight lane, C App Review package, D Integration Testing; tasks are commits on each Epic branch, so there is no per-task PR" },
|
||||
"flash": null,
|
||||
"reset": null,
|
||||
"expires_after_hours": 168
|
||||
}
|
||||
```
|
||||
|
||||
`epic_chain` holds Epics A to D, #1012 to #1015, in order.
|
||||
|
||||
**Basis for the expiry,** stated plainly: 168 hours is the maximum, and it is probably **not enough**. Enrollment review, API approval and beta review are all Apple's clock. Expect one re-mint when Epic B starts.
|
||||
|
||||
## 6. Can't-tell branches
|
||||
|
||||
| Where | Can't tell what | Does |
|
||||
|---|---|---|
|
||||
| Any signed step: a secret is empty or absent | whether the run has credentials | **stop**, naming the secret, never skipping signing or upload |
|
||||
| `.p12` import fails | whether the certificate is usable | **stop** |
|
||||
| Profile UUID or name cannot be read | which profile to sign with | **stop** |
|
||||
| The built `.app` or IPA lacks a native-asset framework | whether storage and translation work | **stop** |
|
||||
| `altool` output contains an error, whatever its exit code | whether the validation passed or the upload landed | **stop** |
|
||||
| The IPA's signing identity cannot be read or is not the Distribution certificate | what was signed | **stop** |
|
||||
| Apple rejects a duplicate build number | whether this build is new | **stop** |
|
||||
| `ios-signing.ps1`: `openssl` not found, or a step's output file is missing | whether the step worked | **stop**, printing what was expected and where |
|
||||
| `set-secrets`: the file to encode does not exist | what would be stored | **stop**, never setting an empty secret |
|
||||
|
||||
No branch proceeds. There is deliberately **no** "skip upload" or dry-run input: a switch that lets a release go green without doing its job is the shape of the #904 override, and a TestFlight upload is private and harmless, so the lane proves itself by actually uploading.
|
||||
|
||||
## 7. Verification
|
||||
|
||||
- **Named command:** `flutter analyze` and `flutter test`, unchanged, plus each Epic's CI run linked in its PR.
|
||||
- **Acceptance bar:**
|
||||
- A1's import check green on the legacy `.p12` and refusing a wrong password, with the default format's result recorded.
|
||||
- B2's signing check red against a wrong certificate name, green against the real one.
|
||||
- B1's framework assertion red on an empty app, green on the real one.
|
||||
- A build in App Store Connect with the expected version and build number.
|
||||
- D1's positive and negative cases all at their expected result on a real iPhone.
|
||||
|
||||
## 8. Done when
|
||||
|
||||
- Offband Meshcore is approved and live on the App Store, iPhone only, every territory except France.
|
||||
- The seller is the owner's legal name, and no contact details are published (non-trader).
|
||||
- The privacy label matches C2, and the offband.org policy names every host.
|
||||
- D1 passed on family devices, and `OUTCOMES.md` is merged.
|
||||
|
||||
## 9. Your choices
|
||||
|
||||
| # | Question | Option A | Option B | Rec. | Your choice |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | Where does each upload's build number come from? | The CI run number, stamped at build time: always unique, never a commit | The pubspec `+N`, matching Android, but every beta then needs a pubspec commit | ⭐ A | A, using the run **ID**: the two callers each count their own run numbers, so run numbers would collide |
|
||||
| 2 | CoreScope sends packet hashes to `map.okimesh.org`, a server you help run. Declare it? | Declare nothing | Declare "Other Data, not linked to the user, App Functionality" | ⭐ B, safe to take unread | B, then replaced on 2026-10-31: the owner hid the Experimental section on iOS, so iOS has nothing to declare (#1051) |
|
||||
| 3 | The support URL App Review requires | A small `offband.org/support` page (`offband-site` work) | The privacy page's contact line | ⭐ A | A |
|
||||
| 4 | Should the GitHub release wait on the iOS upload? | No: an Apple outage cannot block Android and desktop | Yes: all platforms or none | ⭐ A | A |
|
||||
|
||||
The owner approved the plan without naming options, so the recommendations stand, recorded on #200 as reversible.
|
||||
|
||||
Decided already, not choices: Individual enrollment; seller is the legal name; non-trader; France out; public TestFlight link, never email invites; iPhone-only listing; `support@offband.org` as the Apple Account email; Codemagic as fallback only (#957).
|
||||
|
||||
**Alternatives considered but not chosen:**
|
||||
- **Cloud-managed certificates:** no `.p12` at all, but Apple documents it for the Xcode Organizer workflow, and CI would need a broader-role API key. The owner directed the `openssl` path.
|
||||
- **Codemagic:** a recorded fallback, not needed while GitHub's macOS runners work.
|
||||
- **A dry-run upload input:** rejected, section 6.
|
||||
- **Signing in `build.yml`'s PR job:** rejected. A pull request must never run a job that can read signing credentials, the same rule `release-signed.yml` states.
|
||||
|
||||
## 10. Carried-in work
|
||||
|
||||
| Item | Goes to |
|
||||
|---|---|
|
||||
| Privacy policy: add CoreScope and GitHub raw, iOS deletion and permission text, and the support page from choice 3 | A new issue in `OffbandMesh/offband-site`, needed before C5 |
|
||||
| Adding France with the French declaration | Not filed; a later owner decision |
|
||||
| An iPad listing | Not filed |
|
||||
| The BIS page's inconsistent wording on empty years, if the open-source reading ever fails | #958, only if needed |
|
||||
|
||||
When this plan merges, each Epic and Task has a GitHub issue and a Citadel task, per canon.
|
||||
@ -0,0 +1,56 @@
|
||||
# App Review notes and demo video
|
||||
|
||||
For **App Review Information** in App Store Connect and for the beta review (Feature #200, task C3). Paste the block under "Notes" as written, after replacing the video link. Apple's limit is 4,000 bytes.
|
||||
|
||||
## Notes
|
||||
|
||||
```text
|
||||
Offband MeshCore is a client for MeshCore LoRa mesh radios. It needs a MeshCore radio, paired over Bluetooth, to send or receive messages. It sends no messages over the internet and has no account or sign-in.
|
||||
|
||||
DEMO VIDEO
|
||||
A recording of the app running on an iPhone with a real radio, from launch through sending and receiving: <VIDEO LINK>
|
||||
|
||||
WITHOUT A RADIO
|
||||
The app opens to the Bluetooth connection screen and will scan, but chat, contacts and the map's live data need a connected radio. MeshCore radios are third-party hardware, so the video shows these features. We can supply a radio on request.
|
||||
|
||||
WHAT IT DOES
|
||||
Direct messages and group channels over the mesh, contacts, a map of nodes that report a position, delivery and route information, and administration of MeshCore repeaters.
|
||||
|
||||
WHAT YOU MAY NOTICE
|
||||
- Bluetooth permission: used only to talk to the radio. It stays connected in the background (bluetooth-central) so messages arrive with the screen off.
|
||||
- Camera permission: used only to scan QR codes for contacts and communities.
|
||||
- Notification permission: alerts for incoming messages.
|
||||
- Offline translation: optional. A language model is downloaded from Hugging Face only if the user turns translation on, and it runs on the device. This is why the app contains an on-device inference library.
|
||||
- Map tiles come from OpenStreetMap. Line-of-sight checks send the path's coordinates to Open-Meteo for elevation data.
|
||||
- The app does not read the phone's GPS. Positions on the map come from radios.
|
||||
|
||||
USER-GENERATED CONTENT
|
||||
Messages are sent radio to radio. There is no Offband server holding them, so we cannot see, filter or remove them. Users can block a contact from the Contacts screen or a sender from a channel. That drops the contact's direct messages and hides the sender's channel messages. There is no in-app report button, because no one operates a service to receive or act on a report; users can write to support@offband.org. GIF search is limited to Giphy's G rating.
|
||||
|
||||
ENCRYPTION
|
||||
The app uses standard AES, SHA-256 and HMAC from open-source libraries. Its Info.plist sets ITSAppUsesNonExemptEncryption to false, and it is not offered in France. The source code is public: https://github.com/OffbandMesh/meshcore-client
|
||||
```
|
||||
|
||||
## Demo video
|
||||
|
||||
Record on a family iPhone from the TestFlight build, with a second radio or phone in frame to show messages arriving. Use the screen recorder for the app, and film the hardware if you can. No narration needed. Keep it near 2 minutes.
|
||||
|
||||
Before recording, make sure nothing private is visible: use a test channel, a test contact name, and no real location on the map.
|
||||
|
||||
| # | Show | Why Apple needs it |
|
||||
|---|---|---|
|
||||
| 1 | The radio, powered on, beside the iPhone | Proves the hardware is real |
|
||||
| 2 | Launching the app and allowing the Bluetooth prompt | The permission and its reason |
|
||||
| 3 | Picking the radio from the scan list and connecting | The core function |
|
||||
| 4 | Opening a channel and sending a message | Sending |
|
||||
| 5 | The message arriving on the second device, then a reply arriving on the iPhone | Receiving, end to end |
|
||||
| 6 | A direct message to a contact, with its delivery state | Direct chat |
|
||||
| 7 | Contacts, then blocking a test contact | The block control guideline 1.2 asks for |
|
||||
| 8 | The map, with a node showing | Map |
|
||||
| 9 | Scanning a QR code | The camera permission's reason |
|
||||
| 10 | Turning on translation and translating a message, if the model is already downloaded | The on-device model |
|
||||
Upload it unlisted, somewhere that needs no sign-in to watch, and put that link in the notes.
|
||||
|
||||
## The beta review
|
||||
|
||||
Apple reviews the first build sent to an external TestFlight group. Those notes go in **TestFlight > Test Information**, under Beta App Review Information, and the same text works.
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,210 @@
|
||||
import 'dart:typed_data';
|
||||
|
||||
import 'offband_device_ui.dart';
|
||||
|
||||
/// The `0xC5` `0x1C` capability advert (#1095, firmware #1994).
|
||||
///
|
||||
/// Replaces the practice of appending Offband capability bytes to upstream's
|
||||
/// `RESP_CODE_DEVICE_INFO` frame. Three features each computed "the next free
|
||||
/// byte" as **87** and each was right in isolation, and a collision at a frame
|
||||
/// offset is silent misparsing rather than a refused command. Two permanent
|
||||
/// rules came out of that (firmware `docs/offband_info_frame_contract.md` §2):
|
||||
/// no Offband field is ever added to upstream's frame again, and a number is
|
||||
/// claimed by merge before any work begins.
|
||||
///
|
||||
/// THE AUTHORITY for every number here is firmware
|
||||
/// `examples/companion_radio/OffbandConfigProtocol.h`, merged to
|
||||
/// `firmware-base` in PR OffbandMesh/meshcore-firmware#2000 (`28785ebf`,
|
||||
/// 2026-11-04). The contract's §5 table is a convenience copy and the header
|
||||
/// wins on any disagreement. Do not take a number from an Agent Mail message:
|
||||
/// that habit is what caused the collision.
|
||||
const int offbandUiInfoGet = 0x1C;
|
||||
|
||||
/// A tag's PRESENCE is the capability. There is no capability bitmap in this
|
||||
/// frame: tags already answer "is this supported", so a bitmap beside them
|
||||
/// would be a second source of truth for one question (the defect removed from
|
||||
/// contract revision 1).
|
||||
///
|
||||
/// - `len = 0` means "I have this feature, nothing to report". The normal case.
|
||||
/// - `len > 0` only where the value is one or two bytes, fixed for the build,
|
||||
/// and has no sub-code of its own. Everything else is read with its own GET.
|
||||
/// - **Absent** means the board does not have the feature. Not an error, and
|
||||
/// not a zero value.
|
||||
const int offbandInfoTagChanNotify = 0x01;
|
||||
const int offbandInfoTagDisplayRotation = 0x02;
|
||||
const int offbandInfoTagAckCapacity = 0x03;
|
||||
|
||||
/// Display control and LED control are separate capabilities (firmware #2067,
|
||||
/// PR OffbandMesh/meshcore-firmware#2080, merged `c835aeca`): a board can have
|
||||
/// one without the other, and caps2 `0x04` INDICATORS answers both with one
|
||||
/// bit. Values are read over `0x05`/`0x06` and `0x07`/`0x08`.
|
||||
const int offbandInfoTagDisplayControl = 0x04;
|
||||
const int offbandInfoTagLedControl = 0x05;
|
||||
const int offbandInfoTagContinue = 0xFF;
|
||||
|
||||
/// `0x00` is not a valid tag.
|
||||
const int _invalidTag = 0x00;
|
||||
|
||||
/// Firmware `OFFBAND_UI_ERR_MALFORMED = 5`.
|
||||
///
|
||||
/// The `0xC5` handler returns this reason for BOTH a malformed payload on a
|
||||
/// known sub-code and a sub-code it does not implement at all. That overload is
|
||||
/// the entire reason the advert request must carry zero payload: with no
|
||||
/// payload there is nothing to be malformed, so the answer can only mean the
|
||||
/// radio does not implement `0x1C`.
|
||||
const int offbandUiErrReasonMalformed = 0x05;
|
||||
|
||||
/// Ceiling on continuation rounds. The advert is a handful of bytes today and
|
||||
/// no shipping firmware can overflow it, so any long chain is a firmware fault
|
||||
/// rather than a large reply. Bounded because an unbounded request loop driven
|
||||
/// by device data is a worse failure than a truncated capability list.
|
||||
const int offbandInfoMaxContinuations = 8;
|
||||
|
||||
/// Request the whole advert. **Zero payload, deliberately.**
|
||||
///
|
||||
/// A `[0xC5][0x7F][0x05]` answer to a zero-payload request is unambiguous:
|
||||
/// reason 5 is also what a KNOWN sub-code returns for a malformed payload, so
|
||||
/// a request carrying bytes could not be told apart from a device that simply
|
||||
/// predates the advert.
|
||||
Uint8List buildCapabilityAdvertRequestFrame() =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiInfoGet]);
|
||||
|
||||
/// Resume from [cursor], which is the value `TAG_CONTINUE` carried.
|
||||
Uint8List buildCapabilityAdvertResumeFrame(int cursor) {
|
||||
if (cursor < 0 || cursor > 0xFF) {
|
||||
throw ArgumentError.value(cursor, 'cursor', 'must be 0 to 255');
|
||||
}
|
||||
return Uint8List.fromList([cmdOffbandDeviceUi, offbandUiInfoGet, cursor]);
|
||||
}
|
||||
|
||||
/// One `0xC5` `0x1C` reply, parsed.
|
||||
class OffbandCapabilityAdvert {
|
||||
const OffbandCapabilityAdvert({
|
||||
required this.tags,
|
||||
this.continueCursor,
|
||||
this.malformed = false,
|
||||
});
|
||||
|
||||
/// Tag to value. An empty value is the `len = 0` case and still means
|
||||
/// supported, so membership is the question to ask, never emptiness.
|
||||
final Map<int, Uint8List> tags;
|
||||
|
||||
/// Non-null when the reply ended in `TAG_CONTINUE`: re-request with this as
|
||||
/// the cursor. A reply without it is complete.
|
||||
final int? continueCursor;
|
||||
|
||||
/// A record was unparseable and parsing stopped there. The tags BEFORE it are
|
||||
/// still returned, because capability absence is safe (the feature hides)
|
||||
/// while discarding a whole good reply over a bad trailing byte is not.
|
||||
///
|
||||
/// Firmware must not split a record across frames, so this is a firmware
|
||||
/// fault and worth logging rather than swallowing.
|
||||
final bool malformed;
|
||||
|
||||
bool has(int tag) => tags.containsKey(tag);
|
||||
|
||||
/// The single-byte value of [tag], or null when the tag is absent or does not
|
||||
/// carry exactly one byte. Null is never coerced to 0: "the device did not
|
||||
/// say" and "the device said zero" are different answers.
|
||||
int? byteValue(int tag) {
|
||||
final value = tags[tag];
|
||||
if (value == null || value.length != 1) return null;
|
||||
return value[0];
|
||||
}
|
||||
|
||||
@override
|
||||
String toString() {
|
||||
final names = tags.keys.toList()..sort();
|
||||
return 'advert(tags=[${names.map((t) => '0x${t.toRadixString(16).padLeft(2, '0')}').join(',')}]'
|
||||
'${continueCursor == null ? '' : ', continue=0x${continueCursor!.toRadixString(16).padLeft(2, '0')}'}'
|
||||
'${malformed ? ', MALFORMED' : ''})';
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse a `0xC5` `0x1C` reply. Null when the frame is not one of those at all.
|
||||
///
|
||||
/// A reply with no records is valid and means "nothing further", which is what
|
||||
/// a cursor above every available tag returns. It is not an error.
|
||||
///
|
||||
/// Unknown tags are KEPT and skipped by `len`, never rejected: a client built
|
||||
/// today has to stay correct against firmware emitting tags it has never heard
|
||||
/// of, and failing on one is non-conforming.
|
||||
OffbandCapabilityAdvert? parseCapabilityAdvertReply(List<int> frame) {
|
||||
if (frame.length < 2) return null;
|
||||
if (frame[0] != respCodeOffbandDeviceUi) return null;
|
||||
if (frame[1] != offbandUiInfoGet) return null;
|
||||
|
||||
final tags = <int, Uint8List>{};
|
||||
int? continueCursor;
|
||||
var malformed = false;
|
||||
var i = 2;
|
||||
|
||||
while (i < frame.length) {
|
||||
final tag = frame[i];
|
||||
if (tag == _invalidTag) {
|
||||
malformed = true;
|
||||
break;
|
||||
}
|
||||
if (i + 1 >= frame.length) {
|
||||
// A tag with no length byte.
|
||||
malformed = true;
|
||||
break;
|
||||
}
|
||||
final len = frame[i + 1];
|
||||
final valueStart = i + 2;
|
||||
final valueEnd = valueStart + len;
|
||||
if (valueEnd > frame.length) {
|
||||
// A record running past the frame. Firmware must not split one.
|
||||
malformed = true;
|
||||
break;
|
||||
}
|
||||
final value = Uint8List.fromList(frame.sublist(valueStart, valueEnd));
|
||||
|
||||
if (tag == offbandInfoTagContinue) {
|
||||
if (len != 1) {
|
||||
malformed = true;
|
||||
break;
|
||||
}
|
||||
continueCursor = value[0];
|
||||
// TAG_CONTINUE is the last record by construction. Anything after it is
|
||||
// not something to guess at.
|
||||
malformed = valueEnd != frame.length;
|
||||
break;
|
||||
}
|
||||
|
||||
// Records arrive in ascending tag order, but position is never relied on,
|
||||
// so an out-of-order frame still parses. A repeated tag is a firmware
|
||||
// fault: keep the FIRST value and say so, rather than letting a later
|
||||
// record silently redefine a capability.
|
||||
if (tags.containsKey(tag)) {
|
||||
malformed = true;
|
||||
} else {
|
||||
tags[tag] = value;
|
||||
}
|
||||
i = valueEnd;
|
||||
}
|
||||
|
||||
return OffbandCapabilityAdvert(
|
||||
tags: tags,
|
||||
continueCursor: continueCursor,
|
||||
malformed: malformed,
|
||||
);
|
||||
}
|
||||
|
||||
/// How far the client has got with asking this radio for its advert.
|
||||
///
|
||||
/// Distinguishes "has not answered yet" from "answered, and says it does not
|
||||
/// have this mechanism". Those lead to different gating, and a single nullable
|
||||
/// field would conflate them exactly where the collision taught us not to.
|
||||
enum CapabilityAdvertState {
|
||||
/// No request sent, or sent and still outstanding.
|
||||
unknown,
|
||||
|
||||
/// A `0x1C` reply arrived and was parsed.
|
||||
advertised,
|
||||
|
||||
/// `[0xC5][0x7F][0x05]` to our zero-payload request: this radio predates the
|
||||
/// advert, so capability reading falls back to the absolute device-info
|
||||
/// offsets that shipped before it.
|
||||
unsupported,
|
||||
}
|
||||
@ -0,0 +1,111 @@
|
||||
import 'dart:typed_data';
|
||||
|
||||
import 'offband_device_ui.dart';
|
||||
|
||||
/// Per-channel notification mode stored on the RADIO, over `0xC5` 0x18 / 0x19
|
||||
/// (#544, meshcore-firmware#606).
|
||||
///
|
||||
/// This governs the RADIO's buzzer and nothing else. It is deliberately
|
||||
/// independent of the app's own per-channel `ChannelNotifyMode`, which governs
|
||||
/// whether the PHONE notifies: two settings, two outputs, no bridging between
|
||||
/// them (owner, 2026-11-03: "they are separate controls and separate
|
||||
/// notifications... they are independent settings"). Never resolve one from
|
||||
/// the other, and never offer an "inherit the app setting" value here.
|
||||
///
|
||||
/// Firmware is the authority and there is no firmware inherit concept: the
|
||||
/// owner's ruling was "Inherit is on the client side, not on the firmware
|
||||
/// side. How would firmware inherit from firmware?". [unset] is simply the
|
||||
/// absence of a per-channel choice, and the radio's own device-wide scope
|
||||
/// answers for that channel instead.
|
||||
const int offbandUiChannelNotifyGet = 0x18;
|
||||
const int offbandUiChannelNotifySet = 0x19;
|
||||
|
||||
/// A channel's radio notify mode, as the radio stores it.
|
||||
///
|
||||
/// The byte is **1-based** and 0 means "no choice made", because the value
|
||||
/// lives in a field that reads zero on every existing record and every fresh
|
||||
/// channel. If 0 meant a real mode, every untouched channel in the field would
|
||||
/// silently adopt it. The shipped `ChannelTune` byte uses the same convention
|
||||
/// for the same reason, so the two are consistent on the wire.
|
||||
///
|
||||
/// `[verified 2026-11-04 against firmware src/helpers/ChannelNotify.h on
|
||||
/// epic/606-channel-notify: kChanNotifyUnset = 0, kChanNotifyAll = 1,
|
||||
/// kChanNotifyMentions = 2, kChanNotifyOff = 3, kChanNotifyCount = 4.]`
|
||||
/// The contract calls these All / Self / None plus "follow the device
|
||||
/// setting"; that is the same encoding in different words, with "Self" being
|
||||
/// [mentions] and "follow" being [unset].
|
||||
///
|
||||
/// Firmware validates a SET with `stored < kChanNotifyCount`, i.e. `mode < 4`
|
||||
/// and nothing else. That is why a rotation SET on `0x18`/`0x19` was silent
|
||||
/// corruption rather than a refused command: every rotation value in 0 to 3
|
||||
/// passes as a valid notify mode and writes to the channel at that slot. See
|
||||
/// `offband_indicators.dart`, which now uses `0x1A`/`0x1B`.
|
||||
enum RadioChannelNotify {
|
||||
/// No per-channel choice: the radio's device-wide scope answers instead.
|
||||
unset(0x00),
|
||||
|
||||
/// Beep for any message on this channel.
|
||||
all(0x01),
|
||||
|
||||
/// Beep only when the message names us, by the `@[name]` rule.
|
||||
mentions(0x02),
|
||||
|
||||
/// Never beep for this channel.
|
||||
off(0x03);
|
||||
|
||||
const RadioChannelNotify(this.stored);
|
||||
|
||||
/// The wire byte. Never built by hand.
|
||||
final int stored;
|
||||
|
||||
static RadioChannelNotify? fromStored(int stored) {
|
||||
for (final m in RadioChannelNotify.values) {
|
||||
if (m.stored == stored) return m;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/// One channel's radio notify mode, as a `0xC5` 0x18 or 0x19 reply reports it.
|
||||
class RadioChannelNotifyReply {
|
||||
const RadioChannelNotifyReply({required this.channel, required this.mode});
|
||||
final int channel;
|
||||
final RadioChannelNotify mode;
|
||||
}
|
||||
|
||||
int _channelByte(int channel) {
|
||||
if (channel < 0 || channel > 0xFF) {
|
||||
throw ArgumentError.value(channel, 'channel', 'must be 0 to 255');
|
||||
}
|
||||
return channel;
|
||||
}
|
||||
|
||||
Uint8List buildChannelNotifyGetFrame(int channel) => Uint8List.fromList([
|
||||
cmdOffbandDeviceUi,
|
||||
offbandUiChannelNotifyGet,
|
||||
_channelByte(channel),
|
||||
]);
|
||||
|
||||
Uint8List buildChannelNotifySetFrame(int channel, RadioChannelNotify mode) =>
|
||||
Uint8List.fromList([
|
||||
cmdOffbandDeviceUi,
|
||||
offbandUiChannelNotifySet,
|
||||
_channelByte(channel),
|
||||
mode.stored,
|
||||
]);
|
||||
|
||||
/// Parse a `0xC5` channel-notify reply (0x18 or 0x19). Null when this is not
|
||||
/// one, when it is short, or when the mode byte is not a value we know: an
|
||||
/// unrecognized mode is dropped rather than guessed at, so a firmware that
|
||||
/// grows a fourth mode cannot have it read as one of ours.
|
||||
RadioChannelNotifyReply? parseChannelNotifyReply(List<int> frame) {
|
||||
if (frame.length < 4) return null;
|
||||
if (frame[0] != respCodeOffbandDeviceUi) return null;
|
||||
if (frame[1] != offbandUiChannelNotifyGet &&
|
||||
frame[1] != offbandUiChannelNotifySet) {
|
||||
return null;
|
||||
}
|
||||
final mode = RadioChannelNotify.fromStored(frame[3]);
|
||||
if (mode == null) return null;
|
||||
return RadioChannelNotifyReply(channel: frame[2], mode: mode);
|
||||
}
|
||||
@ -0,0 +1,199 @@
|
||||
import 'dart:typed_data';
|
||||
|
||||
import 'offband_capability_advert.dart';
|
||||
import 'offband_device_ui.dart';
|
||||
|
||||
/// The radio's display and LED over `0xC5` (#523, #944): display mode, display
|
||||
/// rotation and the status LED. Gated on caps byte 2 `0x04` INDICATORS
|
||||
/// (meshcore-firmware #542, rotation #1990).
|
||||
///
|
||||
/// display GET `[0xC5][0x05]` -> `[0xC5][0x05][mode]`
|
||||
/// SET `[0xC5][0x06][mode]` -> the same
|
||||
/// led GET `[0xC5][0x07]` -> `[0xC5][0x07][on]`
|
||||
/// SET `[0xC5][0x08][on]` -> the same
|
||||
/// rotation GET `[0xC5][0x1A]` -> `[0xC5][0x1A][deg]`
|
||||
/// SET `[0xC5][0x1B][deg]` -> the same
|
||||
///
|
||||
/// ROTATION IS `0x1A`/`0x1B`, NOT `0x18`/`0x19`. Those are CHNOTIFY, and this
|
||||
/// file held them until 2026-11-04. The collision was not theoretical:
|
||||
/// firmware `4e5a6c85`, already flashed on the owner's T1000-E, answers
|
||||
/// `0x18`/`0x19` as per-channel channel-notify and its SET validates only
|
||||
/// `mode < 4`, so a rotation SET of `0` landed as a valid notify-mode write on
|
||||
/// channel slot 0, which is Public and undeletable, and BOTH sides reported
|
||||
/// success. No error, no banner, nothing in any log.
|
||||
///
|
||||
/// The numbers here are transcribed from firmware
|
||||
/// `examples/companion_radio/OffbandConfigProtocol.h` on `firmware-base` at
|
||||
/// `28785ebf` (PR OffbandMesh/meshcore-firmware#2000). The header is the
|
||||
/// registry. Do not take a sub-code from an Agent Mail message or from this
|
||||
/// comment: read the header, because taking numbers from mail is what caused
|
||||
/// the collision.
|
||||
///
|
||||
/// Rotation is advertised by `TAG_DISPLAY_ROTATION` in the `0xC5` `0x1C`
|
||||
/// advert, NOT by caps2 `0x04` INDICATORS and NOT by probing `0x1A` and
|
||||
/// watching for a refusal. Contract §3 forbids that probing outright:
|
||||
/// "what is forbidden is discovering support by trying each feature's sub-code
|
||||
/// and watching for errors." Display mode and the LED each have their own
|
||||
/// advert tag, with the INDICATORS bit as the fallback: see
|
||||
/// [resolveIndicatorSupport].
|
||||
///
|
||||
/// A board without a display, or without a controllable LED, refuses that
|
||||
/// half with reason 6; a display that cannot turn refuses rotation with 10.
|
||||
|
||||
const int offbandCap2Indicators = 0x04;
|
||||
|
||||
const int offbandUiDisplayGet = 0x05;
|
||||
const int offbandUiDisplaySet = 0x06;
|
||||
const int offbandUiLedGet = 0x07;
|
||||
const int offbandUiLedSet = 0x08;
|
||||
const int offbandUiRotationGet = 0x1A;
|
||||
const int offbandUiRotationSet = 0x1B;
|
||||
|
||||
/// The rotations the radio accepts, in degrees.
|
||||
const List<int> displayRotations = [0, 180];
|
||||
|
||||
bool firmwareSupportsIndicators(int? offbandCaps2) =>
|
||||
offbandCaps2 != null && (offbandCaps2 & offbandCap2Indicators) != 0;
|
||||
|
||||
/// Which indicator controls this radio has, each on its own (#1132, firmware
|
||||
/// #2069).
|
||||
///
|
||||
/// caps2 `0x04` answers display AND LED with one bit, so a board with a real
|
||||
/// display and no controllable LED showed an LED switch the radio then refused
|
||||
/// with `[0xC5][0x7F][0x06]` (firmware #2065: a T096, a T1000-E, a QCC badge).
|
||||
/// Precedence, from the firmware header on `firmware-base`, the same shape as
|
||||
/// channel notify:
|
||||
///
|
||||
/// - the advert carries `TAG_DISPLAY_CONTROL` and/or `TAG_LED_CONTROL`: the
|
||||
/// tags decide, each control on its own, and the bit is ignored;
|
||||
/// - the advert answered with neither tag: firmware from before the tags, so
|
||||
/// the bit answers both, as it always has;
|
||||
/// - no advert (the radio predates `0x1C`, or has not answered yet): the bit
|
||||
/// answers both.
|
||||
///
|
||||
/// The bit is not retired: radios on firmware 1.7.0 and earlier answer the
|
||||
/// advert without these tags, and dropping the bit would hide working display
|
||||
/// control on them. Support is never found by sending a GET and reading the
|
||||
/// refusal (contract §3).
|
||||
({bool display, bool led}) resolveIndicatorSupport({
|
||||
required int? offbandCaps2,
|
||||
required OffbandCapabilityAdvert? advert,
|
||||
}) {
|
||||
if (advert != null &&
|
||||
(advert.has(offbandInfoTagDisplayControl) ||
|
||||
advert.has(offbandInfoTagLedControl))) {
|
||||
return (
|
||||
display: advert.has(offbandInfoTagDisplayControl),
|
||||
led: advert.has(offbandInfoTagLedControl),
|
||||
);
|
||||
}
|
||||
final bit = firmwareSupportsIndicators(offbandCaps2);
|
||||
return (display: bit, led: bit);
|
||||
}
|
||||
|
||||
/// When the radio's screen is lit. Values are the wire encoding.
|
||||
enum DisplayMode {
|
||||
auto(0, 'Auto', 'On while in use, then off after the screen timeout'),
|
||||
alwaysOn(1, 'Always on', 'Never turns off by itself'),
|
||||
alwaysOff(2, 'Always off', 'Stays dark');
|
||||
|
||||
const DisplayMode(this.code, this.label, this.description);
|
||||
final int code;
|
||||
final String label;
|
||||
final String description;
|
||||
|
||||
static DisplayMode? fromCode(int code) {
|
||||
for (final m in DisplayMode.values) {
|
||||
if (m.code == code) return m;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
Uint8List buildDisplayGetFrame() =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiDisplayGet]);
|
||||
|
||||
Uint8List buildDisplaySetFrame(DisplayMode mode) =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiDisplaySet, mode.code]);
|
||||
|
||||
Uint8List buildLedGetFrame() =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiLedGet]);
|
||||
|
||||
Uint8List buildLedSetFrame({required bool on}) =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiLedSet, on ? 1 : 0]);
|
||||
|
||||
Uint8List buildRotationGetFrame() =>
|
||||
Uint8List.fromList([cmdOffbandDeviceUi, offbandUiRotationGet]);
|
||||
|
||||
Uint8List buildRotationSetFrame(int degrees) {
|
||||
if (!displayRotations.contains(degrees)) {
|
||||
throw ArgumentError.value(degrees, 'degrees', 'must be 0 or 180');
|
||||
}
|
||||
return Uint8List.fromList([
|
||||
cmdOffbandDeviceUi,
|
||||
offbandUiRotationSet,
|
||||
degrees,
|
||||
]);
|
||||
}
|
||||
|
||||
/// Parse a display, LED or rotation reply. Null if this is not one, or if it
|
||||
/// is truncated. The shared 0x7F error is owned by [parseButtonMatrixReply].
|
||||
IndicatorReply? parseIndicatorReply(Uint8List frame) {
|
||||
if (frame.length < 3 || frame[0] != respCodeOffbandDeviceUi) return null;
|
||||
final sub = frame[1];
|
||||
final value = frame[2];
|
||||
switch (sub) {
|
||||
case offbandUiLedGet || offbandUiLedSet:
|
||||
return IndicatorReply(sub: sub, ledOn: value != 0);
|
||||
case offbandUiDisplayGet || offbandUiDisplaySet:
|
||||
final mode = DisplayMode.fromCode(value);
|
||||
if (mode == null) {
|
||||
return IndicatorReply(
|
||||
sub: sub,
|
||||
errorMessage:
|
||||
'The radio reported an unknown display mode (${_hex(value)})',
|
||||
);
|
||||
}
|
||||
return IndicatorReply(sub: sub, displayMode: mode);
|
||||
case offbandUiRotationGet || offbandUiRotationSet:
|
||||
if (!displayRotations.contains(value)) {
|
||||
return IndicatorReply(
|
||||
sub: sub,
|
||||
errorMessage: 'The radio reported an unknown rotation ($value)',
|
||||
);
|
||||
}
|
||||
return IndicatorReply(sub: sub, rotation: value);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
String _hex(int b) => '0x${b.toRadixString(16).padLeft(2, '0')}';
|
||||
|
||||
class IndicatorReply {
|
||||
const IndicatorReply({
|
||||
required this.sub,
|
||||
this.displayMode,
|
||||
this.ledOn,
|
||||
this.rotation,
|
||||
this.errorMessage,
|
||||
});
|
||||
|
||||
final int sub;
|
||||
final DisplayMode? displayMode;
|
||||
final bool? ledOn;
|
||||
|
||||
/// Degrees, always one of [displayRotations].
|
||||
final int? rotation;
|
||||
final String? errorMessage;
|
||||
|
||||
DeviceUiSurface get surface => switch (sub) {
|
||||
offbandUiLedGet || offbandUiLedSet => DeviceUiSurface.led,
|
||||
offbandUiRotationGet || offbandUiRotationSet => DeviceUiSurface.rotation,
|
||||
_ => DeviceUiSurface.display,
|
||||
};
|
||||
|
||||
bool get isWrite =>
|
||||
sub == offbandUiDisplaySet ||
|
||||
sub == offbandUiLedSet ||
|
||||
sub == offbandUiRotationSet;
|
||||
}
|
||||
@ -0,0 +1,118 @@
|
||||
import '../models/channel.dart';
|
||||
|
||||
/// One channel to write back to the radio, and where.
|
||||
class ChannelRestoreStep {
|
||||
const ChannelRestoreStep({
|
||||
required this.channel,
|
||||
required this.slot,
|
||||
required this.clearFirst,
|
||||
});
|
||||
|
||||
final Channel channel;
|
||||
final int slot;
|
||||
|
||||
/// The slot holds an erased record. Firmware treats that as occupied
|
||||
/// (#1865), so it is cleared before the channel is written.
|
||||
final bool clearFirst;
|
||||
}
|
||||
|
||||
/// What a restore achieved, as the radio reported it.
|
||||
class ChannelRestoreResult {
|
||||
const ChannelRestoreResult({
|
||||
required this.confirmed,
|
||||
required this.total,
|
||||
required this.notRestored,
|
||||
});
|
||||
|
||||
/// Channels the radio confirmed taking.
|
||||
final int confirmed;
|
||||
|
||||
/// Channels the restore set out to put back.
|
||||
final int total;
|
||||
|
||||
/// Channels the radio refused or never answered for, or had no room for.
|
||||
final List<Channel> notRestored;
|
||||
}
|
||||
|
||||
class ChannelRestorePlan {
|
||||
const ChannelRestorePlan(this.steps, this.noRoom);
|
||||
|
||||
final List<ChannelRestoreStep> steps;
|
||||
|
||||
/// Cached channels with no slot left to go to.
|
||||
final List<Channel> noRoom;
|
||||
}
|
||||
|
||||
/// Decides how to put a radio's lost channels back (#1060, #1117).
|
||||
///
|
||||
/// The client's cached list says which channels the radio had. Replaying each
|
||||
/// one into its remembered slot no longer works on current firmware, which
|
||||
/// refuses a channel over an occupied slot (#1865), treats an erased record
|
||||
/// as occupied, refuses any channel but Public in slot 0, and refuses Public
|
||||
/// anywhere else (#1896). So this places by identity:
|
||||
///
|
||||
/// * A cached channel whose key is already live on the radio, in any slot, is
|
||||
/// left out: the radio has it.
|
||||
/// * Public goes to slot 0. If slot 0 holds a live channel (older firmware
|
||||
/// only), Public takes a free slot instead, so nothing is overwritten.
|
||||
/// * Any other channel goes back to its remembered slot when that slot is
|
||||
/// free or erased and is not slot 0; otherwise to the lowest free slot.
|
||||
/// * A live channel is never a destination, so nothing on the radio is
|
||||
/// overwritten.
|
||||
/// * An erased slot is cleared first.
|
||||
///
|
||||
/// Order does not matter: nothing but Public is ever placed in slot 0, so
|
||||
/// Public always finds it free unless a live channel holds it.
|
||||
ChannelRestorePlan planChannelRestore({
|
||||
required List<Channel> cached,
|
||||
required List<Channel> live,
|
||||
required Set<int> erasedSlots,
|
||||
required int maxChannels,
|
||||
}) {
|
||||
final liveKeys = live.map((c) => c.pskHex).toSet();
|
||||
final taken = live.map((c) => c.index).toSet();
|
||||
final candidates = cached
|
||||
.where((c) => !c.isUnusable && !liveKeys.contains(c.pskHex))
|
||||
.toList();
|
||||
|
||||
final steps = <ChannelRestoreStep>[];
|
||||
final noRoom = <Channel>[];
|
||||
final placedKeys = <String>{};
|
||||
|
||||
bool free(int slot) =>
|
||||
slot >= 0 && slot < maxChannels && !taken.contains(slot);
|
||||
|
||||
int? firstFree() {
|
||||
for (var i = 0; i < maxChannels; i++) {
|
||||
if (i == Channel.publicSlot) continue;
|
||||
if (free(i)) return i;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
for (final channel in candidates) {
|
||||
// A cache can hold the same key twice; write it once.
|
||||
if (!placedKeys.add(channel.pskHex)) continue;
|
||||
final int? slot;
|
||||
if (channel.isPublicChannel) {
|
||||
slot = free(Channel.publicSlot) ? Channel.publicSlot : firstFree();
|
||||
} else if (channel.index != Channel.publicSlot && free(channel.index)) {
|
||||
slot = channel.index;
|
||||
} else {
|
||||
slot = firstFree();
|
||||
}
|
||||
if (slot == null) {
|
||||
noRoom.add(channel);
|
||||
continue;
|
||||
}
|
||||
taken.add(slot);
|
||||
steps.add(
|
||||
ChannelRestoreStep(
|
||||
channel: channel,
|
||||
slot: slot,
|
||||
clearFirst: erasedSlots.contains(slot),
|
||||
),
|
||||
);
|
||||
}
|
||||
return ChannelRestorePlan(steps, noRoom);
|
||||
}
|
||||
@ -0,0 +1,73 @@
|
||||
import '../models/channel.dart';
|
||||
|
||||
/// Why a channel slot could not be allocated.
|
||||
enum ChannelSlotRefusal {
|
||||
/// The channel list is mid-rewrite, so no slot can be trusted to be free.
|
||||
syncing,
|
||||
|
||||
/// Every slot on the radio is in use.
|
||||
full,
|
||||
}
|
||||
|
||||
/// Either a slot that is safe to write, or the reason it was refused.
|
||||
class ChannelSlotDecision {
|
||||
const ChannelSlotDecision.slot(int this.slot) : refusal = null;
|
||||
const ChannelSlotDecision.refused(ChannelSlotRefusal this.refusal)
|
||||
: slot = null;
|
||||
|
||||
final int? slot;
|
||||
final ChannelSlotRefusal? refusal;
|
||||
|
||||
bool get isAllowed => slot != null;
|
||||
}
|
||||
|
||||
/// Decide which channel slot a new channel may occupy (#1021).
|
||||
///
|
||||
/// Pulled out of the channels screen so it can be tested without a widget, and
|
||||
/// so the QR and config-import paths can share one answer instead of each
|
||||
/// carrying their own (there were three divergent implementations, and only one
|
||||
/// of them had the bug).
|
||||
///
|
||||
/// Two refusals, both deliberate:
|
||||
///
|
||||
/// * [isSyncing] true means the connector has emptied its channel list and is
|
||||
/// refilling it slot by slot. Any index would look free. Choosing one here is
|
||||
/// what overwrote Public: a slot picked during a sync pointed at an occupied
|
||||
/// slot by the time it was written.
|
||||
/// * No free index means the radio is full. The caller must be told, never
|
||||
/// handed slot 0 as a consolation, which is the old `return 0` bug and is
|
||||
/// where Public normally lives.
|
||||
///
|
||||
/// Callers pass the connector's `isChannelTableBusy` (a sync, or a write the
|
||||
/// radio has not answered yet), not `hasLoadedChannels`: the latter stays false
|
||||
/// after a *failed* sync while the cached list is restored into use, so gating
|
||||
/// on it would refuse forever on a flaky link.
|
||||
///
|
||||
/// An absent index genuinely means a free slot, because the connector never
|
||||
/// adds an empty channel to its list.
|
||||
///
|
||||
/// Slot 0 is Public's (firmware #1896, owner 2026-10-28: slot 0 "should always
|
||||
/// remain public"). Firmware refuses any other channel there, even while it is
|
||||
/// empty, so [isPublic] false never gets slot 0. Public goes to slot 0 when it
|
||||
/// is free; firmware refuses Public anywhere else, so the fallback to another
|
||||
/// free slot exists only for older firmware, where slot 0 can be held by some
|
||||
/// other channel. [isPublic] is required so no caller can forget the rule.
|
||||
ChannelSlotDecision decideChannelSlot({
|
||||
required List<Channel> channels,
|
||||
required int maxChannels,
|
||||
required bool isSyncing,
|
||||
required bool isPublic,
|
||||
}) {
|
||||
if (isSyncing) {
|
||||
return const ChannelSlotDecision.refused(ChannelSlotRefusal.syncing);
|
||||
}
|
||||
final used = channels.map((c) => c.index).toSet();
|
||||
if (isPublic && !used.contains(Channel.publicSlot)) {
|
||||
return const ChannelSlotDecision.slot(Channel.publicSlot);
|
||||
}
|
||||
for (var i = 0; i < maxChannels; i++) {
|
||||
if (i == Channel.publicSlot) continue;
|
||||
if (!used.contains(i)) return ChannelSlotDecision.slot(i);
|
||||
}
|
||||
return const ChannelSlotDecision.refused(ChannelSlotRefusal.full);
|
||||
}
|
||||
@ -0,0 +1,171 @@
|
||||
import 'dart:typed_data';
|
||||
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
import '../connector/meshcore_connector.dart';
|
||||
import '../l10n/l10n.dart';
|
||||
import '../models/channel.dart';
|
||||
import 'channel_slot_decision.dart';
|
||||
import 'snack_bar_builder.dart';
|
||||
|
||||
/// A channel slot that is safe to write right now, or null after telling the
|
||||
/// user why not (#1021).
|
||||
///
|
||||
/// Every surface that adds a channel goes through this one function: the
|
||||
/// channels screen, the community QR scanner, and anything else that writes a
|
||||
/// slot. That is deliberate. The bug this fixes existed because the same
|
||||
/// question ("which slot is free?") was answered three different ways in three
|
||||
/// files, and only one of them was wrong. One answer cannot drift.
|
||||
///
|
||||
/// Call it at the moment of the write and never earlier. The connector empties
|
||||
/// its channel list for the duration of a channel sync, and `setChannel` itself
|
||||
/// starts one, so a slot chosen before a dialog or a confirmation can point at
|
||||
/// an occupied slot by the time it is written.
|
||||
///
|
||||
/// The owner's ruling is that the unsafe write is blocked but the control stays
|
||||
/// live: a greyed-out button prevents the damage and tells the user nothing. So
|
||||
/// a refusal returns null *and* says what is wrong.
|
||||
///
|
||||
/// [psk] is the key about to be written. Public's key gets slot 0 and nothing
|
||||
/// else does (#1896), and a second copy of Public is refused, whichever path
|
||||
/// the key came in by: Join Public, a typed private key, a QR share, or a
|
||||
/// hashtag join of "public".
|
||||
int? allocateChannelSlotOrExplain(
|
||||
BuildContext context,
|
||||
MeshCoreConnector connector, {
|
||||
required Uint8List psk,
|
||||
}) {
|
||||
final isPublic = Channel.isPublicKey(psk);
|
||||
if (isPublic && refusePublicAlreadyOnRadio(context, connector)) return null;
|
||||
final decision = decideChannelSlot(
|
||||
channels: connector.channels,
|
||||
maxChannels: connector.maxChannels,
|
||||
// Not hasLoadedChannels: that stays false after a FAILED sync while the
|
||||
// cached list is restored, so gating on it would make adding a channel
|
||||
// impossible on a flaky link. Busy also covers a write the radio has not
|
||||
// answered yet (#1026): until it does, the list does not show its slot.
|
||||
isSyncing: connector.isChannelTableBusy,
|
||||
isPublic: isPublic,
|
||||
);
|
||||
switch (decision.refusal) {
|
||||
case ChannelSlotRefusal.syncing:
|
||||
showChannelBlockedMessage(context, context.l10n.channels_slotBusySyncing);
|
||||
return null;
|
||||
case ChannelSlotRefusal.full:
|
||||
showChannelBlockedMessage(
|
||||
context,
|
||||
context.l10n.channels_slotsAllFull(connector.maxChannels),
|
||||
);
|
||||
return null;
|
||||
case null:
|
||||
return decision.slot;
|
||||
}
|
||||
}
|
||||
|
||||
/// A refusal the user has to be able to read and act on, so it persists until
|
||||
/// dismissed.
|
||||
///
|
||||
/// `showDismissibleSnackBar` defaults to `persist: false` and a 4 second toast,
|
||||
/// which SAFELANE 6 rules out for an error.
|
||||
void showChannelBlockedMessage(BuildContext context, String message) {
|
||||
showDismissibleSnackBar(context, content: Text(message), persist: true);
|
||||
}
|
||||
|
||||
/// Explains a channel write the radio did not confirm, and returns true if it
|
||||
/// did. A caller shows its own success message only when this returns false,
|
||||
/// so nothing claims success before the radio has said OK (#1026).
|
||||
///
|
||||
/// A success toast shown after this would replace the explanation (a newer
|
||||
/// toast replaces the visible one), so callers must not show one.
|
||||
bool explainUnconfirmedChannelWrite(BuildContext context, ChannelWrite result) {
|
||||
final l10n = context.l10n;
|
||||
final message = switch (result) {
|
||||
ChannelWrite.ok => null,
|
||||
ChannelWrite.occupied => l10n.channels_writeOccupied,
|
||||
ChannelWrite.rejected => l10n.channels_writeRejected,
|
||||
ChannelWrite.noReply => l10n.channels_writeNoReply,
|
||||
ChannelWrite.clearedNotAdded => l10n.channels_writeClearedNotAdded,
|
||||
ChannelWrite.historyNotMoved => l10n.channels_writeHistoryNotMoved,
|
||||
};
|
||||
if (message == null) return false;
|
||||
showChannelBlockedMessage(context, message);
|
||||
return true;
|
||||
}
|
||||
|
||||
/// Asks what a key change does with [channelName]'s message history: kept
|
||||
/// under the new key, or deleted. Null means the user backed out, and nothing
|
||||
/// may be written (#1128).
|
||||
Future<KeyChangeHistory?> askKeyChangeHistory(
|
||||
BuildContext context,
|
||||
String channelName,
|
||||
) {
|
||||
return showDialog<KeyChangeHistory>(
|
||||
context: context,
|
||||
builder: (dialogContext) {
|
||||
final l10n = dialogContext.l10n;
|
||||
return AlertDialog(
|
||||
title: Text(l10n.channels_keyChangeHistoryTitle),
|
||||
content: Text(l10n.channels_keyChangeHistoryBody(channelName)),
|
||||
actions: [
|
||||
TextButton(
|
||||
onPressed: () => Navigator.pop(dialogContext),
|
||||
child: Text(l10n.common_cancel),
|
||||
),
|
||||
TextButton(
|
||||
style: TextButton.styleFrom(
|
||||
foregroundColor: Theme.of(dialogContext).colorScheme.error,
|
||||
),
|
||||
onPressed: () =>
|
||||
Navigator.pop(dialogContext, KeyChangeHistory.delete),
|
||||
child: Text(l10n.channels_keyChangeDeleteHistory),
|
||||
),
|
||||
FilledButton(
|
||||
onPressed: () =>
|
||||
Navigator.pop(dialogContext, KeyChangeHistory.keep),
|
||||
child: Text(l10n.channels_keyChangeKeepHistory),
|
||||
),
|
||||
],
|
||||
);
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
/// Refuses a second Public channel, and says so. Returns true if it refused.
|
||||
///
|
||||
/// Public is identified by its PSK (`Channel.isPublicChannel`), not by name or
|
||||
/// slot, so this finds it wherever older firmware left it.
|
||||
bool refusePublicAlreadyOnRadio(
|
||||
BuildContext context,
|
||||
MeshCoreConnector connector,
|
||||
) {
|
||||
if (!connector.channels.any((c) => c.isPublicChannel)) return false;
|
||||
showChannelBlockedMessage(context, context.l10n.channels_publicAlreadyAdded);
|
||||
return true;
|
||||
}
|
||||
|
||||
/// For a delete: refuses to remove Public, and says so. Returns true if it
|
||||
/// refused. Firmware #1896 refuses the clear anyway, with the same error code
|
||||
/// as an occupied slot, so without this the user would read the wrong reason
|
||||
/// (owner 2026-10-28: "make sure Public can't be deleted").
|
||||
bool refuseDeletingPublic(BuildContext context, Channel channel) {
|
||||
if (!channel.isPublicChannel) return false;
|
||||
showChannelBlockedMessage(
|
||||
context,
|
||||
context.l10n.channels_publicCannotBeRemoved,
|
||||
);
|
||||
return true;
|
||||
}
|
||||
|
||||
/// For an edit or delete: refuses while the channel list is being re-read or
|
||||
/// a write is unanswered, and says so. Returns true if it refused.
|
||||
///
|
||||
/// Replies are matched to commands by order, so a write sent during a sync
|
||||
/// could take one of the sync's replies as its own.
|
||||
bool refuseWhileChannelTableBusy(
|
||||
BuildContext context,
|
||||
MeshCoreConnector connector,
|
||||
) {
|
||||
if (!connector.isChannelTableBusy) return false;
|
||||
showChannelBlockedMessage(context, context.l10n.channels_slotBusySyncing);
|
||||
return true;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,139 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:package_info_plus/package_info_plus.dart';
|
||||
import 'package:url_launcher/url_launcher.dart';
|
||||
|
||||
import '../../helpers/snack_bar_builder.dart';
|
||||
import '../../l10n/l10n.dart';
|
||||
import '../../utils/platform_info.dart';
|
||||
|
||||
/// The About pane: app identity, version, outbound links and licenses.
|
||||
///
|
||||
/// Needs no radio, so both the device Settings screen and the app-only
|
||||
/// settings reachable from the scanner show it (#693). Outbound links
|
||||
/// (offband.org / Play / donate) added by #527.
|
||||
class AboutView extends StatefulWidget {
|
||||
const AboutView({super.key});
|
||||
|
||||
@override
|
||||
State<AboutView> createState() => _AboutViewState();
|
||||
}
|
||||
|
||||
class _AboutViewState extends State<AboutView> {
|
||||
String _appVersion = '';
|
||||
|
||||
@override
|
||||
void initState() {
|
||||
super.initState();
|
||||
_loadVersionInfo();
|
||||
}
|
||||
|
||||
Future<void> _loadVersionInfo() async {
|
||||
final packageInfo = await PackageInfo.fromPlatform();
|
||||
if (!mounted) return;
|
||||
setState(() {
|
||||
_appVersion = '${packageInfo.version}+${packageInfo.buildNumber}';
|
||||
});
|
||||
}
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final l10n = context.l10n;
|
||||
return ListView(
|
||||
padding: const EdgeInsets.all(16),
|
||||
children: [
|
||||
Card(
|
||||
child: Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
ListTile(
|
||||
leading: const Icon(Icons.info_outline),
|
||||
title: Text(l10n.appTitle),
|
||||
subtitle: Text(
|
||||
l10n.settings_aboutVersion(
|
||||
_appVersion.isEmpty ? l10n.common_loading : _appVersion,
|
||||
),
|
||||
),
|
||||
),
|
||||
Padding(
|
||||
padding: const EdgeInsets.fromLTRB(16, 0, 16, 12),
|
||||
child: Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
Text(l10n.settings_aboutDescription),
|
||||
const SizedBox(height: 12),
|
||||
Text(
|
||||
l10n.settings_aboutLegalese,
|
||||
style: Theme.of(context).textTheme.bodySmall,
|
||||
),
|
||||
const SizedBox(height: 4),
|
||||
Text(
|
||||
l10n.settings_aboutPresetsAttribution,
|
||||
style: Theme.of(context).textTheme.bodySmall,
|
||||
),
|
||||
],
|
||||
),
|
||||
),
|
||||
const Divider(height: 1),
|
||||
ListTile(
|
||||
leading: const Icon(Icons.language),
|
||||
title: Text(l10n.settings_aboutWebsite),
|
||||
trailing: const Icon(Icons.open_in_new, size: 18),
|
||||
onTap: () => _openExternalUrl('https://offband.org'),
|
||||
),
|
||||
// App Store guideline 2.3.10 bars naming other marketplaces (#1048).
|
||||
if (!PlatformInfo.isIOS)
|
||||
ListTile(
|
||||
leading: const Icon(Icons.shop_outlined),
|
||||
title: Text(l10n.settings_aboutPlayStore),
|
||||
trailing: const Icon(Icons.open_in_new, size: 18),
|
||||
onTap: () => _openExternalUrl(
|
||||
'https://play.google.com/store/apps/details?id=app.offband.meshcore',
|
||||
),
|
||||
),
|
||||
// Hidden on iOS for the first App Store submission (#1051).
|
||||
if (!PlatformInfo.isIOS)
|
||||
ListTile(
|
||||
leading: const Icon(Icons.favorite_outline),
|
||||
title: Text(l10n.settings_aboutDonate),
|
||||
trailing: const Icon(Icons.open_in_new, size: 18),
|
||||
onTap: () => _openExternalUrl('https://offband.org/donate'),
|
||||
),
|
||||
const Divider(height: 1),
|
||||
ListTile(
|
||||
leading: const Icon(Icons.description_outlined),
|
||||
title: Text(l10n.settings_aboutLicenses),
|
||||
trailing: const Icon(Icons.chevron_right),
|
||||
onTap: () => showLicensePage(
|
||||
context: context,
|
||||
applicationName: l10n.appTitle,
|
||||
applicationVersion: _appVersion.isEmpty ? null : _appVersion,
|
||||
applicationLegalese: l10n.settings_aboutLegalese,
|
||||
),
|
||||
),
|
||||
],
|
||||
),
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
Future<void> _openExternalUrl(String url) async {
|
||||
try {
|
||||
if (await launchUrl(
|
||||
Uri.parse(url),
|
||||
mode: LaunchMode.externalApplication,
|
||||
)) {
|
||||
return;
|
||||
}
|
||||
} catch (_) {
|
||||
// fall through to the failure message
|
||||
}
|
||||
if (mounted) {
|
||||
showDismissibleSnackBar(
|
||||
context,
|
||||
content: Text(context.l10n.settings_aboutLinkFailed),
|
||||
persist: true,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,43 @@
|
||||
import 'package:flutter/material.dart';
|
||||
|
||||
import '../../l10n/l10n.dart';
|
||||
import 'about_view.dart';
|
||||
import 'app_settings_view.dart';
|
||||
import 'debug_logs_view.dart';
|
||||
import 'settings_shell.dart';
|
||||
|
||||
/// The settings that need no radio, opened from the scanner (#693).
|
||||
///
|
||||
/// A user whose radio will not connect still has to be able to share the log,
|
||||
/// so this offers only app-level categories. Everything that reads or writes
|
||||
/// the radio stays in the device Settings screen, which is reachable only
|
||||
/// while connected. Add a category here only if it works with no radio.
|
||||
class AppOnlySettingsScreen extends StatelessWidget {
|
||||
const AppOnlySettingsScreen({super.key});
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final l10n = context.l10n;
|
||||
return SettingsShell(
|
||||
title: l10n.settings_title,
|
||||
categories: [
|
||||
SettingsCategory(
|
||||
icon: Icons.tune,
|
||||
title: l10n.settings_appSettings,
|
||||
subtitle: l10n.settings_appSettingsSubtitle,
|
||||
builder: (_) => const AppSettingsView(),
|
||||
),
|
||||
SettingsCategory(
|
||||
icon: Icons.build_outlined,
|
||||
title: l10n.settings_debug,
|
||||
builder: (_) => const DebugLogsView(),
|
||||
),
|
||||
SettingsCategory(
|
||||
icon: Icons.info_outline,
|
||||
title: l10n.settings_about,
|
||||
builder: (_) => const AboutView(),
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,136 @@
|
||||
import 'package:flutter/material.dart';
|
||||
import 'package:provider/provider.dart';
|
||||
|
||||
import '../../helpers/snack_bar_builder.dart';
|
||||
import '../../l10n/l10n.dart';
|
||||
import '../../services/app_debug_log_service.dart';
|
||||
import '../../services/app_settings_service.dart';
|
||||
import '../../utils/log_export.dart';
|
||||
import '../app_debug_log_screen.dart';
|
||||
import '../ble_debug_log_screen.dart';
|
||||
|
||||
/// The radio-independent rows of the Debug pane: share the log, the app debug
|
||||
/// logging switch, and the two log viewers.
|
||||
///
|
||||
/// Split out of the device Settings Debug pane (#693) so the scanner's
|
||||
/// app-only settings can offer them with no radio connected. The radio rows
|
||||
/// (Device CLI, serial capture, mesh topology) stay in device Settings.
|
||||
class DebugLogTiles extends StatelessWidget {
|
||||
const DebugLogTiles({super.key});
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
final l10n = context.l10n;
|
||||
final settingsService = context.watch<AppSettingsService>();
|
||||
return Column(
|
||||
mainAxisSize: MainAxisSize.min,
|
||||
children: [
|
||||
ListTile(
|
||||
leading: Icon(LogExport.icon),
|
||||
title: Text(LogExport.tooltip(context)),
|
||||
onTap: () => LogExport.shareLogs(
|
||||
context,
|
||||
webContent: () => LogExport.appLogText(
|
||||
context.read<AppDebugLogService>().entries.reversed,
|
||||
),
|
||||
),
|
||||
),
|
||||
const Divider(height: 1),
|
||||
SwitchListTile(
|
||||
secondary: const Icon(Icons.bug_report_outlined),
|
||||
title: Text(l10n.appSettings_appDebugLogging),
|
||||
subtitle: Text(l10n.appSettings_appDebugLoggingSubtitle),
|
||||
value: settingsService.settings.appDebugLogEnabled,
|
||||
onChanged: (value) async {
|
||||
try {
|
||||
await settingsService.setAppDebugLogEnabled(value);
|
||||
} catch (_) {
|
||||
if (context.mounted) {
|
||||
showDismissibleSnackBar(
|
||||
context,
|
||||
content: const Text(
|
||||
'Could not change debug logging. Please try again.',
|
||||
),
|
||||
persist: true,
|
||||
);
|
||||
}
|
||||
return;
|
||||
}
|
||||
if (!context.mounted) return;
|
||||
showDismissibleSnackBar(
|
||||
context,
|
||||
content: Text(
|
||||
value
|
||||
? l10n.appSettings_appDebugLoggingEnabled
|
||||
: l10n.appSettings_appDebugLoggingDisabled,
|
||||
),
|
||||
duration: const Duration(seconds: 2),
|
||||
);
|
||||
},
|
||||
),
|
||||
const Divider(height: 1),
|
||||
ListTile(
|
||||
leading: const Icon(Icons.bluetooth_outlined),
|
||||
title: Text(l10n.settings_companionDebugLog),
|
||||
subtitle: Text(l10n.settings_companionDebugLogSubtitle),
|
||||
trailing: const Icon(Icons.chevron_right),
|
||||
onTap: () {
|
||||
Navigator.push(
|
||||
context,
|
||||
MaterialPageRoute(
|
||||
builder: (context) => const BleDebugLogScreen(),
|
||||
),
|
||||
);
|
||||
},
|
||||
),
|
||||
const Divider(height: 1),
|
||||
ListTile(
|
||||
leading: const Icon(Icons.code_outlined),
|
||||
title: Text(l10n.settings_appDebugLog),
|
||||
subtitle: Text(l10n.settings_appDebugLogSubtitle),
|
||||
trailing: const Icon(Icons.chevron_right),
|
||||
onTap: () {
|
||||
Navigator.push(
|
||||
context,
|
||||
MaterialPageRoute(
|
||||
builder: (context) => const AppDebugLogScreen(),
|
||||
),
|
||||
);
|
||||
},
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/// The Debug pane of the app-only settings: the log rows in their own card.
|
||||
class DebugLogsView extends StatelessWidget {
|
||||
const DebugLogsView({super.key});
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
return ListView(
|
||||
padding: const EdgeInsets.all(16),
|
||||
children: [
|
||||
Card(
|
||||
child: Column(
|
||||
crossAxisAlignment: CrossAxisAlignment.start,
|
||||
children: [
|
||||
Padding(
|
||||
padding: const EdgeInsets.fromLTRB(16, 16, 16, 8),
|
||||
child: Text(
|
||||
context.l10n.settings_debug,
|
||||
style: const TextStyle(
|
||||
fontSize: 18,
|
||||
fontWeight: FontWeight.bold,
|
||||
),
|
||||
),
|
||||
),
|
||||
const DebugLogTiles(),
|
||||
],
|
||||
),
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue