Developer Docs.

SecureBin Developer Platform

Build privacy-focused apps with standard HTML, CSS, and JavaScript, then submit provider-blind encrypted review envelopes for marketplace approval. SecureBin App Store uploads accept .sbapp-review.enc.json submissions only.

Review envelopes

The SDK encrypts marketplace submissions to the SecureBin review key before upload.

Signed releases

Approved source is converted into an official signed transport by the trusted publisher.

Web-native development

Use familiar browser technologies and preview locally with the included development server.

Keep private keys private. The public SDK contains no generated private keys. Never upload or commit .securebin/app.key, .securebin/signing-private.pem, the SecureBin review private key, or the publisher private key.

Overview

A SecureBin project contains a readable local source directory and a manifest. The SDK turns those files into an encrypted review envelope with the .sbapp-review.enc.json extension. Only that review envelope is submitted to the App Store.

Quick Start

Extract the SDK, open PowerShell in the extracted folder, and run:

node bin/securebin.js create my-app
cd my-app
node ..\bin\securebin.js keygen
node ..\bin\securebin.js dev

Open the loopback URL printed by the development server. When the app is ready, stop the server and build the encrypted marketplace review envelope:

node ..\bin\securebin.js submit --review-key review-public.pem --out dist\my-app.sbapp-review.enc.json

Upload dist\my-app.sbapp-review.enc.json at Upload App. The upload form rejects legacy .sbapp, .html, and .htm files for public marketplace submission.

Project Structure

The starter includes a .gitignore that excludes .securebin/ and dist/. Back up the package key securely outside source control.

Manifest

The SDK validates securebin.app.json before development and packaging.

{
  "id": "com.example.my-app",
  "name": "My App",
  "version": "1.0.0",
  "source": "src",
  "entry": "index.html",
  "permissions": ["storage.local"]
}

Permissions

Declare only the runtime capabilities your app needs in securebin.app.json.

App Store listing permissions are also selected on the upload form. Keep those declarations consistent with the manifest and app behavior.

Runtime API

The included runtime/securebin-runtime.js exposes window.securebin. Include it from /securebin-runtime.js while using the SDK development server.

<script src="/securebin-runtime.js" defer></script>
<script src="app.js" defer></script>

Host calls use a request/response bridge and time out after 30 seconds. Handle rejected promises and unavailable capabilities in your UI.

Security Model

Packaging happens locally. The hosting provider stores and serves the encrypted envelope but does not receive the package key.

Current package encryption is AES-256-GCM. The SDK signs the encrypted ciphertext hash with Ed25519 when signing keys are available.

Key loss is permanent. If you lose app.key, you may be unable to decrypt or update packages built with that key. Store a secure backup.

Packaging

The submission builder recursively includes files from the manifest's source directory, hashes each file, builds a review artifact, and encrypts it to the SecureBin review public key.

node ..\bin\securebin.js submit --review-key review-public.pem --out dist\my-app.sbapp-review.enc.json

The upload envelope contains format, version, app_id, payload_hash, review-key metadata, and ciphertext. The web host can validate and quarantine it, but cannot read the source.

securebin package still exists for legacy private distribution, but public marketplace upload rejects those opaque .sbapp packages because they cannot be reviewed before publication.

Publishing and Updates

1. Test locally

   Run dev and verify the app without depending on undeclared capabilities.

2. Build a review envelope

   Run submit --review-key review-public.pem and upload the generated .sbapp-review.enc.json.

3. Owner review

   SecureBin reviews the decrypted source in the restricted review dashboard before any marketplace publishing step.

4. Publish after approval

   Only the trusted publisher converts approved review content into an official signed .sbapp. Developers do not upload signed transports directly.

5. Update an existing app

   Submit a new .sbapp-review.enc.json for the replacement version. The marketplace should not accept direct legacy package replacement.

Icons, screenshots, pricing, descriptions, and App Store listing permissions are entered separately on the website and are bound to the review record.

In-App Purchases

In-app purchases are available for approved marketplace apps. Developers can define one-time or subscription products on the app upload/edit page. Apps can request a checkout session and check whether the signed-in user has active access to a product.

Each product is defined with an id, name, and type of either one_time or subscription. One-time products take a flat price; subscription products take price_monthly and price_yearly.

[
  {"id":"pro","name":"Pro unlock","type":"one_time","price":4.99},
  {"id":"plus","name":"Plus","type":"subscription","price_monthly":2.99,"price_yearly":19.99}
]

Apps should start checkout through the SecureBin in-app checkout launcher. This creates a SecureBin-controlled checkout session and opens the integrated checkout UI:

<script src="/assets/js/securebin-iap.js"></script>
<button data-securebin-iap data-app-slug="your-app-slug" data-product-id="pro">
  Unlock Pro
</button>

Apps can also call the launcher directly after a button or link click:

SecureBinIAP.openCheckout({
  appSlug: "your-app-slug",
  productId: "pro"
});

For native or advanced integrations, apps can request a checkout session from SecureBin with:

POST /assets/php/create_in_app_checkout.php
{ "app_slug": "your-app-slug", "product_id": "pro" }

The response contains a SecureBin-controlled checkout_url and checkout_session. The checkout session is bound to the signed-in user, app, product, product type, expected price, and a short expiration window.

Purchase and subscription records are completed only by the integrated checkout callback. Direct app-side calls to the record endpoints are rejected with integrated_checkout_required.

Controlled checkout flow

App button or link click
  -> SecureBin creates checkout session
  -> SecureBin opens hosted checkout
  -> Payment completes inside the integrated checkout
  -> Signed checkout callback records the purchase or subscription
  -> App checks access through check_in_app_access.php
  -> Revenue dashboard includes the transaction

The integrated checkout callback must include a valid HMAC signature header. Configure the shared callback secret with SECUREBIN_IAP_CALLBACK_SECRET or the securebin_settings key in_app_checkout_callback_secret.

X-SecureBin-IAP-Signature: sha256=<hmac_sha256_raw_json_body>

One-time products are tracked in in_app_purchases; subscription products are tracked in in_app_subscriptions. Both are included in developer revenue totals and payout balance.

Apps can check whether the signed-in user currently has access to a product with:

GET /assets/php/check_in_app_access.php?app=your-app-slug&product=pro

Troubleshooting