title: "اثبات مالکیت بسته و ابزار balestore-proof" order: 10 description: "توکن اثبات مالکیت، ساخت APK اثبات با CLI یا پروژهٔ الگو، بررسی محلی، بارگذاری و کدهای خطا"
اثبات مالکیت بسته و ابزار balestore-proof
اولین بار که یک نام بسته را در بلهاستور ثبت میکنید، باید ثابت کنید کلید امضای آن برنامه دست شماست. این کار جلوی ثبت برنامههای دیگران به نام شما را میگیرد و هیچوقت کلید خصوصی شما را از رایانهتان خارج نمیکند.
روند کلی
- پس از بارگذاری اولین APK، کنسول یک توکن یکبارمصرف نشان میدهد (برنامه ← مالکیت).
- یک APK اثبات کوچک میسازید که:
- همان نام بسته (
package/applicationId) برنامهٔ شما را دارد؛ versionCodeآن ۱ است (هر عددی پذیرفته میشود؛ این فایل هرگز منتشر نمیشود)؛- توکن را در یک
<meta-data>داخل<application>دارد:<meta-data android:name="ir.bale.balestore.OWNERSHIP_TOKEN" android:value="bsp1-…" /> - با همان کلید امضای برنامه و با طرح v2 یا v3 امضا شده است (امضای فقط-v1 رد میشود).
- همان نام بسته (
- آن را بارگذاری و ثبت میکنید؛ بلهاستور نام بسته، توکن، انقضا و گواهی امضا را بررسی میکند.
- در صورت موفقیت، وضعیت مالکیت
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 همان پروژه):
- نام بسته را در متغیر محیطی
PROOF_PACKAGEو توکن کنسول را درPROOF_TOKENبگذارید (یا-PproofPackage=… -PproofToken=…). - همان keystore و alias برنامهٔ اصلی را با
PROOF_KEYSTORE،PROOF_ALIAS،PROOF_STOREPASS(و در صورت نیازPROOF_KEYPASS) معرفی کنید؛ امضای v2/v3 در الگو فعال است. ./gradlew assembleReleaseرا اجرا کنید؛ ساخت با نام بسته یا توکن نامعتبر متوقف میشود.- فایل
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) اقدام کنید.