a2 / passcards-swift

A simple Apple Wallet server.

Passcards

A simple Wallet server that implements the PassKit Web Service requirements. (This is a Swift re-implementation of the original Parse-backed version.)

Building

$ swift build -c release
$ .build/release/App

Required Environment

Key	Description
APNS_KEY_ID	APNS key ID
APNS_PRIVATE_KEY	APNS private key content
APNS_TEAM_ID	APNS team ID
APNS_TOPIC	APNS (certificate) topic
PG_DBNAME	Postgres database name
PG_HOST	Postgres host
PG_PASSWORD	Postgres password
PG_PORT	Postgres port
PG_USER	Postgres user
S3_ACCESS_KEY	S3 access key
S3_BUCKET	S3 bucket name
S3_REGION	S3 bucket region
S3_SECRET_KEY	S3 access secret key
UPDATE_PASSWORD	Update password (unset == unlimited access)

Deployment

1. Create an app on Heroku

   $ heroku apps:create [NAME]

2. Set the environment variables (as described above)

   $ heroku config:set X=abc Y=def Z=ghi ...

   If you use the Heroku PostgreSQL plugin, you will need to add the plugin (which sets the DATABASE_URL environment variable) and then set the required PG_* variables.

3. Install the Container Registry Plugin

   $ heroku plugins:install heroku-container-registry

4. Build and deploy Docker image to Heroku

   $ heroku container:push web

5. Open the website (a static single-page site)

   $ heroku open

Usage

Creating a Pass

This is beyond the scope of the project, but recommended reading includes:

• Wallet Developer Guide: Building Your First Pass, Pass Design and Creation
• PassKit Package Format Reference

You will want to set https://my-heroku-app.herokuapp.com/ as the webServiceURL root key in your pass.json.

Example passes, as well as the source of a command-line tool for signing Pass bundles (signpass), can be found here.

Uploading a Pass

$ curl -X POST \
    -H "Authorization: Bearer MY_UPDATE_PASSWORD" \
    -F "pass=@a_local_file.pkpass" \
    -F "authentication_token=AUTHENTICATION_TOKEN" \
    -F "pass_type_identifier=PASS_TYPE_IDENTIFIER" \
    -F "serial_number=SERIAL_NUMBER" \
    https://my-heroku-app.herokuapp.com/VANITY_URL.pkpass

In the above cURL command, a_local_file.pkpass is a file in the current working directory. Set the authentication_token, pass_type_identifier, and serial_number fields to their corresponding values from the pass's pass.json. MY_UPDATE_PASSWORD is the UPDATE_PASSWORD environment variable set in your app.

Updating a Pass

$ curl -X PUT \
    -H "Authorization: Bearer MY_UPDATE_PASSWORD" \
    -F "pass=@a_local_file.pkpass" \
    https://my-heroku-app.herokuapp.com/VANITY_URL.pkpass

a_local_file.pkpass is the new local file to replace on the server. MY_UPDATE_PASSWORD is the same UPDATE_PASSWORD as above.

Sharing a Pass

A Pass recipient can go to https://my-heroku-app.herokuapp.com/VANITY_URL.pkpass to receive your pass.

Author

Alexsander Akers, [email protected]

My Personal Set-up

On my personal website (https://pass.a2.io), I use CloudFlare to secure the website subdomain that points to Heroku because then I get TLS / HTTPS (which is required for PassKit in production) for free, because I'm cheap. To that extent, I also use Heroku's free PostgreSQL plan and the free dyno hours.

A sleeping-when-idle Heroku app is perfect for Wallet services because an iOS device will call your service endpoints in the background and retry upon timeout.

Your app service service is only woken...

1. when someone adds a pass (triggering a pass registration).
2. when someone deletes a pass (triggering pass de-registration).
3. when someone triggers a manual refresh of a pass.
4. when someone toggles "Automatic Updates" on the backside of a pass (shown with the ⓘ button).

License

Passcards is available under the MIT license. See the LICENSE file for more info.