Credential handling

Store, rotate and revoke PMT tokens safely.

PMT separates send and read capability so a source can report without automatically gaining access to stored results, and a viewer can read without gaining a write path.

Give each token only the scope its job requires.

Token roles

Current scopes support ingress/send, egress/read, or both.

send-only  → no PIN
read-only  → shared account PIN
send+read  → project-specific PIN

A project token labelled “Admin” does not grant PMT operator/admin privileges.

Use the narrowest practical token

• Reporting source: normally send-only.
• Webapp/read client: normally read-only.
• Combined client: send+read only when genuinely required.

Prefer project/token separation when viewers need materially different data.

Token lifecycle

active
deprecating
suspended
revoked

Deprecating supports the approved overlap window during rotation. Token expiry is checked separately from these status values.

Rotation pattern

create replacement
→ deploy replacement
→ verify it works
→ overlap briefly if required
→ revoke old token
→ verify old token fails

Ordinary large deployments should not require an unsafe all-at-once credential swap.

Where tokens live matters.

A one-off test and a long-lived fleet deployment do not require the same handling discipline.

WEBAPP / READ TOKEN

The current webapp persists read tokens in browser localStorage.

Browser configuration exports can include read tokens.

The PIN is held in memory and omitted from those exports.

Emergency revocation

1. revoke or suspend the affected token;
2. find deployed/exported copies;
3. issue a replacement if still needed;
4. update source/viewer;
5. verify old access fails;
6. review scripts and exports.

Current read-cache caveat

Egress caches successful token/PIN authorisations.

A revocation or suspension can therefore stop access after the cached authorisation expires rather than at the instant the database record changes.

Do not describe revocation as an instantaneous HTTP traffic block.

Server-side token protection

• HMAC-SHA256 aliases for lookup;
• Argon2id hashes for token/PIN verification;
• encrypted token/PIN copies for controlled reveal/delivery.

Magic-link reveal/delivery is single-use. Treat a valid reveal link as sensitive.

Important boundaries

Token scope does not provide:

• per-station ACLs;
• per-sensor ACLs;
• cryptographic proof of physical source identity from stn;
• instant cache-free revocation on every read path;
• protection from administrators who already control the endpoint.

PMT deliberately keeps the credential model small.