Skip to content

About

Time-limited WiFi voucher access with gateway-enforced expiry. Generate codes, validate at a captive portal, and cut off access server-side, no client-side timer to bypass.

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

38 Commits

Folders and files

Repository files navigation

token-access

A voucher access system for shared internet: generate time-limited codes, hand them out, and have access cut off automatically when the time is up. Built for the business-center / cafe / venue case where you want to give someone an hour or a day of WiFi and not think about it again.

The whole design turns on one thing: the time limit is enforced on the gateway, not on the user's device. There's nothing on the client to tamper with, so a user can't reset the timer, reuse an expired code, or route around the limit.

This repo is the working model of that: code generation, validation, server-side session expiry, revocation, an optional email-verification flow, and a gateway abstraction that a real captive portal plugs into.

The guarantee, concretely

A voucher code is just a record. On its own it grants nothing. It only means something when checked against server-side state, and the countdown that ends a session lives with the gateway, keyed to the session rather than the device. So:

  • Changing the device clock does nothing. The gateway holds the time.
  • Reconnecting or clearing the browser does nothing. The session record persists.
  • An expired or already-spent code is rejected on re-entry.
  • A code is bound to its device allowance, so it can't be shared past it.
  • When anything is wrong, the default is no access. Fail closed.

Install

Python 3.9+.

pip install -e .

State lives in a local SQLite database by default (tokenaccess.db). No external services are required for the core voucher flow; SMTP is only needed if you turn on email verification.

Using it

Generate vouchers:

tokenaccess generate --duration 1h
tokenaccess generate --duration 15m --count 50 --batch lobby-oct
tokenaccess generate --duration 1d --devices 3 --note "conference room"

--duration takes 15m, 1h, 1d, 1w, or a custom length like 90m.

Validate a code (this is what the captive portal calls when a user enters one):

tokenaccess validate 7QK4M2P9RT --device aa:bb:cc:dd:ee:ff

On success it starts a session and the gateway grants that device access for exactly the voucher's duration. When the duration elapses the sweeper ends the session and the device is returned to the portal.

Admin:

tokenaccess list --state active
tokenaccess revoke 7QK4M2P9RT          # kill a code and any live session on it
tokenaccess export --batch lobby-oct --out vouchers.csv
tokenaccess serve                       # run the session sweeper (expiry enforcement)

How enforcement works

  1. Generate. An admin makes a voucher bound to a duration, a device allowance, and optional metadata. It's stored server-side as unused.
  2. Validate. A user enters the code at the portal. The gateway checks it against the records; if it's usable, a session starts and the start time is recorded server-side.
  3. Grant. The device is granted network access for the voucher's duration through the gateway backend.
  4. Expire. A background sweeper watches session expiry times. When one passes, it revokes the grant and the device drops back to the portal. Nothing on the device participates in this.

Email verification (optional)

For the airport / coffee-shop style flow where people self-register:

  1. User connects, lands on the portal, enters an email.
  2. The portal sends a verification code over SMTP.
  3. On verification, the gateway starts a session of the configured duration.
  4. Optionally a short provisional window is granted while the email is in flight, then confirmed or revoked.

Email decides whether to start a session; the gateway still owns how long it lasts. Same enforcement model underneath.

Deployment shape

This is designed to sit on top of existing network gear, not replace it:

  • On a managed gateway with a built-in hotspot/voucher engine, this maps onto the gateway's own configuration -- usually the cheapest route since it reuses hardware that's already there.
  • Where you need a custom portal or the email step, run a small captive-portal service (the local gateway backend here models that) while the gateway stays the point of enforcement.
  • For a fully custom flow, an open platform like OpenNDS is an option; there's an opennds backend that shells out to its client-control interface.

See examples/deployment.md for a worked configuration.

Design notes

  • Enforcement belongs on the gateway. A timer on the user's device can always be defeated; keeping it server-side is what makes the limit real.
  • Codes are records, not secrets that carry their own authority. That's what stops reuse and sharing.
  • Reuse existing hardware where you can. A native voucher engine on gear you already run is simpler to hand over than new infrastructure.
  • Fail closed. Invalid or expired means no access, never open access.

MIT licensed.

About

Time-limited WiFi voucher access with gateway-enforced expiry. Generate codes, validate at a captive portal, and cut off access server-side, no client-side timer to bypass.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages