auth.proto

// SPDX-FileCopyrightText: Copyright (c) 2026 APN
// SPDX-License-Identifier: MIT

syntax = "proto3";
package proto;

// Auth is sent by the client to the Node as the first application
// message after the TLS handshake. The Node verifies the HMAC tag
// against its current (and previous) pre-shared key and uses the
// recovered identity to set up the tunnel session.
message Auth {
  // Stable client identifier, exactly nine raw UTF-8 bytes; signed
  // by the HMAC together with timestamp. Not a UUID — the Hub
  // generates it once per installation.
  bytes client_id = 1;

  // Minutes since the project epoch (2024-01-01 UTC), used as a
  // replay-prevention nonce. The Node accepts the message only if
  // this value is within one minute of its own clock.
  uint32 timestamp = 2;

  // Truncated HMAC-SHA256 (12 bytes) over (client_id || timestamp),
  // computed with the pre-shared key issued to this client. Proves
  // possession of the PSK without revealing it.
  bytes hmac = 3;

  // Free-form device label reported by the client (e.g. "iPhone15,3",
  // "Pixel 8"). Recorded by the Hub for usage analytics; not used
  // for authentication.
  string device = 4;

  // Client locale tag (BCP-47, e.g. "en-US"), passed through to the
  // Hub for analytics and for localised server-side notifications.
  string locale = 5;

  // Random bytes appended so that the encrypted message size varies
  // across sessions. Defeats traffic-analysis fingerprinting of the
  // Auth frame; the Node ignores the contents.
  bytes padding = 6;

  // Version of the APN client software sending the request, in the
  // form "<store>:<semver>", where the store is a single letter
  // naming the marketplace the build was released to: "A" for the
  // Apple App Store, "G" for Google Play, "H" for Huawei AppGallery
  // (e.g. "A:1.1.1", "G:1.1.1", or "H:1.1.1"). Forwarded by the
  // Node to the Hub for usage analytics; not used for authentication.
  string version = 7;

  // Screen dimension of the client device in physical pixels, in the
  // form "<width>x<height>" (e.g. "1179x2556"). Forwarded by the Node
  // to the Hub for usage analytics; not used for authentication.
  string screen = 8;
}