title: "اثبات مالکیت بسته و ابزار balestore-proof" order: 10 description: "توکن اثبات مالکیت، ساخت APK اثبات با CLI یا پروژهٔ الگو، بررسی محلی، بارگذاری و کدهای خطا"

اثبات مالکیت بسته و ابزار balestore-proof

اولین بار که یک نام بسته را در بله‌استور ثبت می‌کنید، باید ثابت کنید کلید امضای آن برنامه دست شماست. این کار جلوی ثبت برنامه‌های دیگران به نام شما را می‌گیرد و هیچ‌وقت کلید خصوصی شما را از رایانه‌تان خارج نمی‌کند.

روند کلی

  1. پس از بارگذاری اولین APK، کنسول یک توکن یک‌بارمصرف نشان می‌دهد (برنامه ← مالکیت).
  2. یک APK اثبات کوچک می‌سازید که:
    • همان نام بسته (package / applicationId) برنامهٔ شما را دارد؛
    • versionCode آن ۱ است (هر عددی پذیرفته می‌شود؛ این فایل هرگز منتشر نمی‌شود)؛
    • توکن را در یک <meta-data> داخل <application> دارد:
      <meta-data android:name="ir.bale.balestore.OWNERSHIP_TOKEN" android:value="bsp1-…" />
      
    • با همان کلید امضای برنامه و با طرح v2 یا v3 امضا شده است (امضای فقط-v1 رد می‌شود).
  3. آن را بارگذاری و ثبت می‌کنید؛ بله‌استور نام بسته، توکن، انقضا و گواهی امضا را بررسی می‌کند.
  4. در صورت موفقیت، وضعیت مالکیت VERIFIED می‌شود و فایل اثبات از سرور پاک می‌شود.

قالب توکن

bsp1-<32 lowercase base32 characters [a-z2-7]>      e.g. bsp1-z5xn5trykgdj7jyz5o3libuaavvjnw6q
  • ۱۶۰ بیت تصادفی؛ مخصوص یک نام بسته و یک سازمان.
  • اعتبار: ۷ روز. اگر منقضی شد، از کنسول توکن تازه بگیرید (POST /console/v1/apps/{appId}/ownership/token) و APK اثبات را دوباره بسازید.
  • وضعیت فعلی: GET /console/v1/apps/{appId}/ownership ← {status, token, expiresAt, verifiedAt, certEvidence, certConflict}.

ابزار balestore-proof

ابزاری خط‌فرمانی که APK اثبات را بدون Gradle می‌سازد و بررسی می‌کند. پیش‌نیازها: Python 3، JDK (۱۱ به بالا) و Android SDK Build-Tools (aapt2، zipalign، apksigner). یک تصویر Docker هم دارد که همهٔ این‌ها را همراه دارد.

balestore-proof build  --package PKG --token bsp1-… --keystore KS --alias ALIAS
                       [--storepass P] [--keypass P] [--out proof.apk] [--min-sdk 24] [--target-sdk 35] [--json]
balestore-proof verify APK --token bsp1-… [--package PKG] [--cert AB:CD:…]... [--json]
balestore-proof gen-token        # a random token-shaped value, for local demos only

build

  • توکن (bsp1- + ۳۲ نویسهٔ [a-z2-7]) و نام بسته را اعتبارسنجی می‌کند.
  • APKی با همان نام بسته، versionCode = ۱ و بدون کد (android:hasCode="false") می‌سازد و توکن را در <meta-data> می‌گذارد.
  • با کلید شما و طرح‌های v2 + v3 (و v1) امضا می‌کند.
  • رمزها را از گزینه‌ها، یا متغیرهای محیطی BALESTORE_STOREPASS / BALESTORE_KEYPASS، یا با پرسش تعاملی می‌گیرد (رمز کلید به‌طور پیش‌فرض همان رمز keystore است). رمزها از طریق متغیر محیطی به apksigner داده می‌شوند، نه در خط فرمان.
  • اثر انگشت SHA-256 گواهی امضا (AB:CD:…) و گام‌های بعدی را (فارسی و انگلیسی) چاپ می‌کند.

verify

همان بررسی‌های سرور را محلی انجام می‌دهد:

بررسی کد شکست
نام بسته برابر --package OWNERSHIP_PACKAGE_MISMATCH
مقدار meta-data برابر --token OWNERSHIP_TOKEN_MISMATCH
امضای معتبر v2 یا v3 (فقط-v1 رد می‌شود) SIGNATURE_SCHEME / SIGNATURE_INVALID (برچسب محلی CLI)
هر گواهی امضاکننده در فهرست --cert باشد (اختیاری) OWNERSHIP_CERT_MISMATCH

کد خروج: 0 = درست، 1 = عدم تطابق یا APK نامعتبر، 2 = آرگومان نادرست. انقضای توکن (OWNERSHIP_TOKEN_EXPIRED) فقط در سرور قابل بررسی است.

برای --cert اثر انگشت گواهی برنامه را از کنسول (برنامه ← signingCertSha256) بردارید یا با apksigner verify --print-certs app-release.apk ببینید.

نمونهٔ گام‌به‌گام

# 1) token: copy it from the console (App → Ownership). For a local dry run you can generate a token-shaped value:
TOKEN=bsp1-z5xn5trykgdj7jyz5o3libuaavvjnw6q        # or: TOKEN=$(balestore-proof gen-token)

# 2) build the proof APK with YOUR app's signing key
BALESTORE_STOREPASS='…' balestore-proof build \
  --package com.example.app --token "$TOKEN" \
  --keystore ~/keys/release.jks --alias release --out proof.apk
# → signing cert SHA-256: 6D:4F:FD:5F:…:B9:39:DD:EF   (must equal your app's certificate)

# 3) verify locally before uploading (optionally pin your app certificate)
balestore-proof verify proof.apk --token "$TOKEN" --package com.example.app --cert 6D:4F:FD:5F:…:B9:39:DD:EF
balestore-proof verify proof.apk --token bsp1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   # → FAIL [OWNERSHIP_TOKEN_MISMATCH], exit 1

گام ۴: بارگذاری. ساده‌ترین راه، دکمهٔ «بارگذاری APK اثبات» در کنسول است. با API:

API=https://api.<domain>; AUTH="Authorization: Bearer $CONSOLE_TOKEN"
SIZE=$(stat -c %s proof.apk)

UPLOAD_ID=$(curl -fsS -X POST "$API/console/v1/uploads" -H "$AUTH" -H 'content-type: application/json' \
  -d "{\"orgId\":\"$ORG_ID\",\"fileName\":\"proof.apk\",\"sizeBytes\":$SIZE,\"purpose\":\"ownership_proof\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["uploadId"])')

# a proof APK is a few KB → one part
curl -fsS -X PUT "$API/console/v1/uploads/$UPLOAD_ID/parts/1" -H "$AUTH" \
  -H 'content-type: application/octet-stream' --data-binary @proof.apk
curl -fsS -X POST "$API/console/v1/uploads/$UPLOAD_ID/complete" -H "$AUTH"

curl -fsS -X POST "$API/console/v1/apps/$APP_ID/ownership/proof" -H "$AUTH" \
  -H 'content-type: application/json' -d "{\"uploadId\":\"$UPLOAD_ID\"}"
# → {"status":"VERIFIED", …}

با Docker

docker run --rm -it -v "$PWD:/work" -w /work balestore/proof \
  build --package com.example.app --token bsp1-… --keystore release.jks --alias release --out proof.apk

پروژهٔ الگو (Gradle)

اگر ترجیح می‌دهید با Gradle و تنظیمات امضای همیشگی پروژه کار کنید، از پروژهٔ الگوی android/ownership-proof-template/ استفاده کنید؛ یک پروژهٔ Gradle حداقلی و بدون کد که فقط manifest با meta-data توکن دارد. مراحل (جزئیات در README همان پروژه):

  1. نام بسته را در متغیر محیطی PROOF_PACKAGE و توکن کنسول را در PROOF_TOKEN بگذارید (یا -PproofPackage=… -PproofToken=…).
  2. همان keystore و alias برنامهٔ اصلی را با PROOF_KEYSTORE، PROOF_ALIAS، PROOF_STOREPASS (و در صورت نیاز PROOF_KEYPASS) معرفی کنید؛ امضای v2/v3 در الگو فعال است.
  3. ./gradlew assembleRelease را اجرا کنید؛ ساخت با نام بسته یا توکن نامعتبر متوقف می‌شود.
  4. فایل app/build/outputs/apk/release/app-release.apk را با balestore-proof verify بررسی و بارگذاری کنید.

نمونهٔ بخش‌های اصلی:

// app/build.gradle.kts (excerpt)
android {
    namespace = "ir.bale.balestore.proof"
    defaultConfig {
        applicationId = System.getenv("PROOF_PACKAGE") ?: "com.example.app"   // ← your package name
        versionCode = 1
        versionName = "proof"
        minSdk = 24
    }
    signingConfigs {
        create("release") {
            storeFile = file(System.getenv("PROOF_KEYSTORE") ?: "release.jks")
            storePassword = System.getenv("PROOF_STOREPASS")
            keyAlias = System.getenv("PROOF_ALIAS") ?: "release"
            keyPassword = System.getenv("PROOF_KEYPASS") ?: System.getenv("PROOF_STOREPASS")
            enableV2Signing = true
            enableV3Signing = true
        }
    }
    buildTypes { release { signingConfig = signingConfigs.getByName("release"); isMinifyEnabled = false } }
}
<!-- app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application android:hasCode="false" android:label="proof">
        <meta-data
            android:name="ir.bale.balestore.OWNERSHIP_TOKEN"
            android:value="${ownershipToken}" />   <!-- manifestPlaceholders["ownershipToken"] = PROOF_TOKEN -->
    </application>
</manifest>

⚠️ اگر برنامهٔ اصلی با Play App Signing یا امضای دیگری توزیع می‌شود، دقت کنید APK اثبات باید با همان کلیدی امضا شود که APKهای بارگذاری‌شده در بله‌استور با آن امضا شده‌اند.

کدهای خطا

کد علت راه رفع
OWNERSHIP_TOKEN_MISMATCH مقدار ir.bale.balestore.OWNERSHIP_TOKEN در APK با توکن فعلی کنسول یکی نیست (یا meta-data وجود ندارد) توکن را دوباره از کنسول کپی کنید (بدون فاصلهٔ اضافه) و APK را دوباره بسازید. اگر توکن را دوباره صادر کرده‌اید، توکن قبلی دیگر معتبر نیست.
OWNERSHIP_CERT_MISMATCH همهٔ گواهی‌های امضاکنندهٔ APK اثبات جزو گواهی‌های برنامه (گواهی‌های اولین نسخهٔ بارگذاری‌شده) نیستند با همان keystore و alias برنامه امضا کنید. با balestore-proof verify --cert و apksigner verify --print-certs مقایسه کنید.
OWNERSHIP_PACKAGE_MISMATCH نام بستهٔ APK اثبات با نام بستهٔ برنامه یکی نیست --package (یا applicationId در پروژهٔ الگو) را دقیقاً برابر نام بستهٔ برنامه بگذارید؛ پسوندهایی مثل .debug نباید اضافه شوند.
OWNERSHIP_TOKEN_EXPIRED بیش از ۷ روز از صدور توکن گذشته است از کنسول توکن تازه بگیرید و APK اثبات را دوباره بسازید.
OWNERSHIP_NOT_VERIFIED پیش از تکمیل اثبات مالکیت، نسخه برای بررسی ارسال شده است ابتدا اثبات مالکیت را کامل کنید.

پرسش‌های رایج

آیا کلید خصوصی‌ام به بله‌استور فرستاده می‌شود؟ خیر. امضا روی رایانهٔ شما انجام می‌شود و فقط APK امضاشده بارگذاری می‌شود. بله‌استور هرگز کلید امضای شما را نمی‌خواهد.

برنامه‌ام در بازار یا مایکت هم هست؛ کافی است؟ اثبات در اختیار داشتن کلید همیشه لازم است. علاوه بر آن، گواهی امضای فایل شما باید با نسخهٔ موجود در فروشگاه دیگر یکی باشد. منبع این مقایسه در حال نهایی‌شدن است؛ فعلاً می‌توانید شواهد را دستی ارسال کنید (POST /console/v1/apps/{appId}/ownership/evidence، مثلاً با پیوند صفحهٔ برنامه در فروشگاه دیگر).

گواهی من زیر سازمان دیگری هم دیده شده. اگر یک گواهی امضا زیر دو سازمان نامرتبط ظاهر شود، هر دو برنامه برای بررسی علامت می‌خورند (certConflict: true). اگر کسی بستهٔ شما را ثبت کرده، از مسیر ادعای مالکیت (POST /console/v1/disputes) اقدام کنید.