KiwiStack

№ A · 03 / Authorization & trust

The customer's
physical security boundary.

Every action sensitive enough to matter, from opening a ticket and enrolling a device to wiping a stolen laptop, granting administrator rights, or changing jurisdiction, is gated by a YubiKey signature. Software-only authentication is replaceable by phone-call social engineering. Cryptographic signatures from a hardware token are not.

№ Z1 / What it gates

Every action,
graded by sensitivity.

The required signature(s) for each operation are codified in the customer's state repo (policies/authorization.yaml) and enforced by the per-tenant authorization service. Policies are themselves changed by Critical-tier signed actions.

Sensitivity

Operation

Required signatures

Low

Open a support ticket on support.kiwistack.io

Any 1 YubiKey signature in the customer's roster

Read tenant audit log / billing / status

Any 1 YubiKey signature

Medium

Enroll a new device

1 sig from a key with role ≥ sysadmin

Create / disable a Nubus user

1 sig from a key with role ≥ sysadmin

Quota / group changes

1 sig from a key with role ≥ sysadmin

High

Remote lock / wipe a device

1 sig from a key with role ≥ sysadmin

Rotate the customer's smallstep intermediate

1 sig from founder key + KiwiStack operator co-sign

Critical

Add or remove an administrator

2 distinct cert sigs (founder + sysadmin) within 5 min

Change jurisdiction / hosting region

2 sigs + 7-day cancellable delay + KiwiStack operator confirm

Tenant deletion

2 sigs + 14-day cancellable delay + KiwiStack operator confirm

"Role" is the value of the OU field in the YubiKey's PIV cert subject (founder, sysadmin, office-mgr, …). The server reads the cert when it validates the signature; role is cryptographically asserted, not just claimed.

№ Z2 / Hardware

YubiKey 5 Series.
FIPS for the regulated.

Standard hardware: YubiKey 5 Series (5C NFC by default). Full protocol stack: PIV (X.509 in non-extractable hardware), FIDO2/WebAuthn, OATH, OpenPGP. Authentication by PIN + touch, the same model used by US federal PIV cards, NHS smartcards, eIDAS-grade national IDs. Premium SKU: YubiKey 5 FIPS Series for customers under eIDAS, US-equivalent, or sectoral regulated obligations: same form factor, FIPS 140-3 validated crypto.

Slot / applet

What it stores · what it does

PIV slot 9a (auth)

Per-admin X.509 keypair, generated on-device, never extractable. Public key signed by the customer's smallstep intermediate. Subject names the admin and role: CN=Marie Schmidt, OU=founder, O=acme-corp.

FIDO2 / WebAuthn

Used by the helpdesk portal sign-in flow at support.kiwistack.io. Same key, different applet.

OATH-HOTP / TOTP

Optional second factor for non-cert operations (e.g. customer's own internal tools, third-party SaaS where the customer maps the YubiKey as MFA).

OpenPGP

Available but unused in our default flows. Customer can use it for git-commit signing, email, etc. on their own.

Yubico attestation

Yubico's chain proves the key is a real YubiKey 5 Series. Recorded in the customer registry at issuance.

What is NOT on the key

  • → No customer data. No mail, files, contacts.
  • → No password store. Vaultwarden lives in the cluster, not the key.
  • → No private key extractable by software. PIV slots are write-only from outside; the secure element signs but never exports.
  • → No backdoor for KiwiStack operators. We hold an audit log of issuance, nothing more.

№ Z3 / Distribution

Per-role keys.
One human, one key, one cert.

Each customer admin gets their own YubiKey. Each key's PIV cert subject names the admin and their role. The server reads the cert when validating a signature; role isn't claimed in a header, it's cryptographically asserted by the cert chain. Lose a key, only that admin's authority is exposed; revoke at smallstep, ship a replacement, the rest of the roster unaffected.

Sample roster · acme-corp · Mesh tier

Key alias

Holder

Role

Notes

founder.yubikey

Marie Schmidt

founder

All operations · only key authorized for the second sig on Critical ops

sysadmin.yubikey

John Doe

sysadmin

Day-to-day ops · device enrollment, user management, remote wipe

office-mgr.yubikey

Anne Lefèvre

office-mgr

Read-only and ticket-opening · cannot enrol devices or change users

on-call-backup.yubikey

(emergency)

sysadmin

Held in a sealed envelope in the office safe for sysadmin's vacations

Volume per tier: Core → optional, Mesh → 2 included (founder + sysadmin), Fleet → up to 5 included. Replacements / additions at cost (€70–95 each for 5 Series, €90–95 for 5 FIPS). Customer can keep an "on-call backup" key in a sealed safe envelope; revoke + reissue if seal is broken.

№ Z4 / Policy as code

Versioned.
Auditable. Reviewable.

The customer's authorization policy is a YAML file in their state repo, reconciled by Argo CD, enforced by the per-tenant authorization service. To change a policy is itself a Critical-tier action. two signatures from the customer's roster, optionally a cancellable delay, audit log entry on every change. 

# customer state repo: policies/authorization.yaml

operations:
  open_ticket:
    sensitivity: low
    sigs_required: 1
    role: any

  enroll_device:
    sensitivity: medium
    sigs_required: 1
    role: sysadmin

  remote_wipe:
    sensitivity: high
    sigs_required: 1
    role: sysadmin

  add_admin:
    sensitivity: critical
    sigs_required: 2
    roles: [founder, sysadmin]
    window: 5m

  tenant_delete:
    sensitivity: critical
    sigs_required: 2
    roles: [founder, sysadmin]
    window: 14d
    operator_cosign: true
    cancellable: true

roster:
  - serial: 12345678
    admin: Marie Schmidt
    role: founder
  - serial: 12345679
    admin: John Doe
    role: sysadmin
  - serial: 12345680
    admin: Anne Lefèvre
    role: office-mgr

The shape above is illustrative. Roles and operation list are extensible per customer. Defaults (sensible policies for a new tenant) ship in the customer template; customers tune from there with a Critical-tier signed PR.

№ Z5 / Action, traced

From request
to applied,
in seven hops.

Same flow whether the action came from the CLI, the helpdesk portal, or an API call. Critical-tier ops add the second-signature wait and the cancellable delay.

01

Action requested

An admin invokes a privileged operation, via the kiwistack-enroll CLI on a laptop, the helpdesk portal, or an API call.

02

Server checks policy

The customer's per-tenant authorization service reads policies/authorization.yaml. Looks up the operation's sensitivity, the required role, the n-of-m signature count.

03

Challenge issued

Server returns a challenge: nonce + operation digest + required-roles list + window (typically 5 min for Critical).

04

Admin signs with their YubiKey

PIN entered, key touched. PIV slot 9a signs the challenge. Cert subject names the admin and role; signature chains to the customer's smallstep intermediate.

05

Server validates

Verify chain to MSP root (or to the customer's BYOC trust anchor). Check role meets policy. Check time window. For Critical ops, wait for the second signature from a different key with the required complementary role.

06

Action applies

All sigs collected and policy satisfied → action applies. For Very Critical ops, action is staged with a cancellable delay (7d / 14d) and KiwiStack operator co-sign.

07

Audit log written

Every step logged: which key serial, which admin, which action, when. Customer can read their own log via support.kiwistack.io.

№ Z6 / Helpdesk portal

support.kiwistack.io
A sketch of design intent.

A multi-tenant ticket portal where every privileged ticket carries a YubiKey signature. Browser sign-in via WebAuthn (FIDO2). Tickets that request a privileged operation (e.g. "wipe lost laptop X") are themselves signed actions; the portal stages a Critical-tier authorization flow, asks for a second signature if needed, and either applies the action or escalates to a KiwiStack operator.

Status

Planned, not yet built. Sketched here as design intent so customers and operators can see the trajectory of the authorization model. The per-tenant authorization service, the helpdesk portal front-end, and the time-delay broker are net-new components scoped for a later iteration. Today's tickets go through a temporary email + Keycloak login flow that does not require a YubiKey signature: a stepping stone, not the destination.

№ Z7 / BYOC alternative

Bring your
own certificate.

For customers who already have personal certs (a YubiKey from a previous job, a corporate smartcard, an internal-CA-issued cert, an eIDAS QSCD), the alternative is to bring those certs and have us trust them. We don't take over your cert lifecycle; we just add the certs to your tenant's trust list. Same authorization service, same policy model, just signatures from your existing identity instead of from a YubiKey we shipped you.

DEFAULT

Per-role YubiKey 5 Series

We ship the keys, we provision the certs, we operate the chain. One key per admin. FIPS variant on request. The path of least resistance.

ALTERNATIVE

BYOC. Bring your own certificate

Customer brings one cert per admin. We add them to the per-tenant trust list (a ConfigMap in the state repo). Customer holds their certs on whatever they like: a YubiKey from another vendor, a smartcard, software. Off-boarding: drop the certs from the trust list, done.

→ BYOCA footnote: customers with mature in-house PKI (EJBCA, ADCS, OpenXPKI) can bring a full CA root instead of individual certs; we plug their root into smallstep as a trust anchor. Ask if relevant.