BYO (Bring-Your-Own) Reader Provisioning

Status: DESIGNED, NOT IMPLEMENTED. This page describes the planned BYO provisioning model for customer-owned R700 readers.

What BYO Means

BYO (Bring-Your-Own) = Customer has R700 hardware already on-site (bought from distributor, or already owned). Customer installs CAP themselves, then claims reader into their Titan Cloud account via hub UI.

vs Wonder-Shipped:

	Wonder-Shipped	BYO
Hardware Source	Wonder buys and ships	Customer owns
CAP Install	Pre-installed at bench	Customer installs
Identity	Pre-provisioned at bench	Customer claims + pulls
Network Exposure	None (bench LAN only)	Bootstrap endpoint (internet)
Customer Steps	1 (plug in)	3 (install CAP, claim, bootstrap)
When Available	Available now (Wonder-shipped)	Designed, awaiting Security approval

Why BYO Is Needed

Use cases:

• Customer already owns R700 readers (bought from Impinj distributor)
• Customer adding readers to existing Titan Cloud account (expand fleet)
• Large customer wants to buy hardware directly (lower cost, bulk orders)
• Customer wants to test Titan with existing hardware before committing

Constraint: Wonder cannot touch hardware. Provisioning must be self-service over internet.

BYO Workflow (Planned)

Step 1: Install CAP on Reader

Customer side (on-site, with physical access to reader):

1. Download CAP .upgx from https://get.titanrfid.com/cap/latest.upgx
2. Open reader web UI: https://<reader-ip>/
3. Set CAP install mode: Open (Settings → CAP)
4. Upload CAP (Apps → Upload Application)
5. Set Persistent Data = rw_dir
6. Start CAP

At this point:

• CAP installed and running
• No identity (CAP cannot connect to MQTT yet)
• Reader not claimed (no tenant binding)

Step 2: Claim Reader in Hub

Customer logs into hub.titanrfid.com:

1. Navigate to Readers → Add Reader → Claim BYO Reader
2. Enter reader's serial number (from label on hardware): 370-12-34-5678-9012
3. Click Claim

Backend (POST /api/v1/readers/claim):

• Checks serial not already claimed
• Checks customer has reader quota (license)
• Issues client certificate (CN = reader serial number)
• Creates reader row in customer's account
• Creates device binding (serial → tenant)
• Generates claim token: ct_3YhD8f9K2mP5xN7qR4vW6zL8cT1bV0sA
• Expires in 5 minutes

Hub UI shows:

Claim successful!

Copy this command and run it on your reader:

  curl -fsSL "https://bootstrap.titanrfid.com/pull/ct_3YhD8f9K2mP5xN7qR4vW6zL8cT1bV0sA?serial=370-12-34-5678-9012" \
    | titan-agent bootstrap

Expires in 5 minutes. Reader will appear online after bootstrap completes.

Step 3: Bootstrap Reader

Customer runs command on reader (SSH or via CAP UI future feature):

curl -fsSL "https://bootstrap.titanrfid.com/pull/ct_3YhD8f...?serial=370-12-34-5678-9012" \
  | titan-agent bootstrap

What bootstrap does:

1. CAP fetches GET /pull/{token}?serial={serial} (validates token+serial match)
2. Response contains:
   • ca.crt (Titan Cloud CA)
   • client.crt (reader's cert, CN = reader serial number)
   • client.key (private key)
   • titan.json (REST credentials)
   • MQTT config (broker address, topics)
3. CAP writes all 4 files to /cust/rw_dir/
4. CAP restarts, reads identity from rw_dir
5. CAP connects to mqtt.titanrfid.com:8883 with client cert
6. CAP subscribes to titan/v1/370-12-34-5678-9012/commands
7. CAP publishes initial status on command-response topic

Hub UI updates:

• Reader status changes from "Claimed, awaiting bootstrap" → Online
• Start/Stop buttons become active
• Tag reads begin appearing

Total time: ~2 minutes (CAP restart + MQTT connection + first status update)

Security Architecture

Full security architecture is documented internally (not on this public site). Key points:

Claim Authorization

• Only org principals can claim (authenticated users, not API keys)
• Serial exclusivity: One reader, one tenant (global uniqueness enforced)
• Audited: Every claim, pull, and bootstrap logged with user_id, timestamp, IP

Token Security

• Opaque: 192-bit entropy, base62-encoded, ct_ prefix
• Single-use: Consumed on first pull; second attempt returns 404
• Short TTL: 5 minutes (not renewable)
• Scoped: Token + serial must match (cannot use token for different reader)
• Hashed: SHA-256 stored in DB (plaintext never at rest)

Certificate Binding

• CN = reader serial: Client cert Common Name is the reader serial number (MQTT topic identity)
• Broker ACL: use_identity_as_username true → MQTT username = cert CN
• Topic enforcement: Reader can only publish/subscribe to titan/v1/{CN}/*
• Revocation: Titand revoke (operator console) stops Titan accepting a reader's data but does not update the broker revocation list. After support or Wonder revokes the certificate on the broker, the reader is refused at its next connection; an existing connection continues until it drops (no fixed time bound). Release (operator console only) unassigns the tenant when requested via support. Re-provisioning issues a new certificate but does not revoke the old one; contact support or Wonder to revoke the old certificate if it must not reconnect.

Pull Endpoint

• Host: bootstrap.titanrfid.com (separate subdomain, rate-limited)
• Auth: Token + serial validation (mutual TLS optional, query param fallback)
• Rate limits: 10 req/min per IP, 1000 req/min global
• DDoS protection: Cloudflare Workers in front

What Cannot Be Attacked

• Cannot enumerate valid serials (no /devices list endpoint)
• Cannot reuse token (single-use, consumed on pull)
• Cannot guess token (192-bit entropy, 5-min TTL)
• Cannot forge cert (requires CA signing key)
• Cannot impersonate reader (cert CN checked by broker ACL)

Advantages and Trade-Offs

vs Wonder-Shipped

Advantages:

• Customer owns hardware (lower cost, bulk orders)
• No Wonder shipping delay (hardware already on-site)
• Works with existing Impinj R700 fleets

Trade-Offs:

• 3-step setup vs 1-step (plug-in)
• Larger attack surface (internet-exposed bootstrap endpoint)
• Higher support burden (customer-side install errors)
• Requires customer to run command on reader (SSH or CAP UI)

When to Use Each

Wonder-Shipped:

• Small fleets (1-5 readers)
• Customer has no IT staff
• Prefer plug-and-play experience
• Security-sensitive (no internet exposure during provisioning)

BYO:

• Customer already owns R700 hardware
• Large fleets (>10 readers) where bulk purchase is cheaper
• Customer comfortable with CLI or SSH
• Customer wants to test Titan before committing to hardware

Implementation Status

Designed: Security architecture complete (internal design doc)

Not Implemented:

• Claim API (POST /api/v1/readers/claim)
• Pull API (GET /pull/{token})
• Bootstrap logic in CAP (titan-agent bootstrap)
• Hub UI (claim flow, token display)
• Certificate issuance pipeline
• Automated certificate revocation publishing (BYO pipeline)
• Cloudflare Workers for bootstrap subdomain

Blocker: Awaiting Security re-gate approval. Implementation begins only after Security clearance.

Timeline: TBD (pending Security approval)

Open Questions

See the internal design doc for the full list. Key questions:

1. Mutual TLS on pull: Should pull API require client cert, or is query param ?serial=... sufficient?
2. Revocation behavior: How should release or re-issue affect an already-connected reader?
3. Token renewal: If pull fails (network error), should token be renewable, or must customer re-claim?

What Customers Will See (Future)

When implemented, BYO claiming will appear in hub UI as:

Readers → Add Reader

┌─────────────────────────────────────────┐
│ How do you want to add a reader?       │
│                                          │
│ ○  Ship from Wonder (recommended)       │
│    Reader arrives configured. Just plug │
│    it in.                                │
│                                          │
│ ●  Claim my own reader (BYO)            │
│    I already have an R700 on-site.      │
│                                          │
│    Serial number: [370-12-34-5678-9012] │
│                                          │
│    [Claim Reader]                        │
└─────────────────────────────────────────┘

After claim, customer sees:

• Claim token (copy-paste command)
• Expiry countdown (5 minutes)
• Instructions: "Run this command on your reader via SSH"

For Now: Wonder-Shipped Only

Until BYO is implemented, all readers must be Wonder-Shipped. Customers who want to use existing hardware should contact Wonder support to arrange bench provisioning (ship reader to Wonder, provision, ship back).

Alternative for dev/lab: Manual provisioning (see CAP Install for manual identity provisioning). Not suitable for production.

Next Steps

• Wonder-Shipped - Current Wonder-shipped provisioning model
• CAP claim-and-pull security design - Internal repository doc (not published here); full architecture for BYO
• CAP Install - Manual CAP installation (dev/lab only)