Open Site Pass

Standar kode QR terbuka untuk registrasi di lokasi kerja. Aplikasi apa pun dapat menampilkan pas, dan kios apa pun dapat membacanya.

Versi 1, November 2026. Bebas digunakan di bawah CC BY 4.0.

Kontraktor melakukan registrasi di lokasi yang berbeda setiap minggu, dan setiap lokasi meminta detail yang sama: nama, perusahaan, nomor ponsel, kendaraan, kartu Site Safe. Open Site Pass memungkinkan mereka membawa detail tersebut di aplikasi dan menyerahkannya dengan menunjukkan kode QR. Aplikasi apa pun dapat menampilkan pas, dan kios registrasi apa pun dapat membacanya, siapa pun pembuatnya.

Sebelum menulis ini, kami mencari standar yang sudah ada. Produk registrasi tamu yang menggunakan pas QR masing-masing memiliki format sendiri yang hanya berfungsi di dalam produk tersebut. Standar identitas umum (W3C Verifiable Credentials, OpenID for Verifiable Presentations, SIM seluler ISO 18013-5) memerlukan aplikasi dompet dan pertukaran multi-langkah, yang terlalu berlebihan untuk tablet di gerbang lokasi. Jadi ini adalah format kecil yang dapat dibaca dan diperiksa oleh bahasa pemrograman apa pun dengan kriptografi bawaannya.

1. Isi kode QR

Kode QR berisi teks biasa dalam tiga bagian yang digabungkan dengan titik:

OSP1.<pass>.<signature>
  • OSP1 menyatakan bahwa ini adalah Open Site Pass, versi 1.
  • <pass> adalah pas dalam JSON, UTF-8, lalu base64url tanpa padding.
  • <signature> adalah tanda tangan ECDSA P-256 dengan SHA-256 atas teks ASCII <pass> (persis seperti yang muncul di kode QR), dalam bentuk r ‖ s 64 byte, lalu base64url tanpa padding. Ini adalah bentuk yang dihasilkan crypto.subtle.sign dari Web Crypto.

2. Pas

{
  "version": 1,
  "issuer": "https://timeclock.kiwi",
  "keyId": "2026-11-3fa9c1",
  "holderId": "b7f3c2e1a94d0c55e1f3b2a8",
  "issuedAt": "2026-11-01T09:42:00.000Z",
  "expiresAt": "2026-11-01T09:43:00.000Z",
  "firstName": "Sam",
  "lastName": "Taylor",
  "company": "Harbour Electrical Ltd",
  "phone": "+64215550142",
  "vehicleRegistration": "QKT482",
  "documents": [
    { "type": "site-safe-passport", "number": "SS-482913", "expiresOn": "2027-03-31" }
  ]
}
versionSelalu 1 untuk versi ini.
issuerOrigin HTTPS pihak yang menandatangani pas, mis. https://timeclock.kiwi. Kuncinya ditemukan dari sini.
keyIdKunci penerbit mana yang menandatanganinya.
holderIdSama untuk satu orang dengan satu penerbit, dan berbeda untuk setiap penerbit lain. Memungkinkan lokasi mengenali tamu yang kembali. Tidak boleh berupa nomor karyawan, email, atau apa pun yang mengidentifikasi mereka di tempat lain.
issuedAt, expiresAtWaktu ISO 8601. Pas sebaiknya berlaku sekitar satu menit dan tidak boleh lebih dari 15 menit, sehingga foto pas cepat tidak berguna.
firstName, lastNameNama mereka.
companyTempat mereka bekerja, jika mereka memilih membagikannya.
phoneNomor ponsel, sebaiknya dalam format internasional.
emailAlamat email.
vehicleRegistrationNomor pelat kendaraan yang mereka gunakan.
documentsKartu dan sertifikat: masing-masing memiliki type (dari daftar di bawah), dan opsional number, issuer, dan expiresOn (YYYY-MM-DD).

Wajib: version, issuer, keyId, holderId, issuedAt, expiresAt, firstName. Selebihnya opsional dan dipilih oleh pemegang setiap kali.

Jenis dokumen

site-safe-passportSite Safe passport
public-liability-insuranceAsuransi tanggung gugat publik
electrical-registrationRegistrasi kelistrikan
plumbing-gasfitting-registrationRegistrasi pipa, gas, atau saluran pembuangan
forklift-licenceLisensi forklift (endorsemen F)
first-aid-certificateSertifikat pertolongan pertama
working-at-heightsBekerja di ketinggian
confined-spacesRuang terbatas
construction-induction-cardKartu induksi konstruksi (White Card)
cscs-cardCSCS card

Untuk mengusulkan jenis lain, hubungi kami di bawah. Kios menyimpan dokumen dengan jenis yang tidak dikenalnya, tetapi tidak mencocokkannya dengan apa pun.

3. Kunci penerbit

Penerbit memublikasikan kunci publiknya di <issuer>/.well-known/open-site-pass/keys.json:

{
  "keys": [
    {
      "keyId": "2026-11-3fa9c1",
      "publicKey": { "kty": "EC", "crv": "P-256", "x": "…", "y": "…" }
    }
  ]
}

Setiap publicKey adalah JWK, yang dapat dimuat langsung oleh Web Crypto. Tetap publikasikan kunci setidaknya satu hari setelah Anda berhenti menandatangani dengannya. Kunci Timeclock.Kiwi ada di https://timeclock.kiwi/.well-known/open-site-pass/keys.json.

4. Aturan untuk kios

  1. Periksa tanda tangan dengan kunci penerbit, dan pastikan pas belum kedaluwarsa. Beri toleransi hingga 2 menit ke depan maupun ke belakang untuk perbedaan jam.
  2. Hanya ambil kunci dari origin HTTPS milik penerbit itu sendiri, dan simpan dalam cache agar pas dapat diperiksa secara offline.
  3. Tampilkan detail dan domain penerbit, dan biarkan tamu mengonfirmasi sebelum apa pun disimpan.
  4. Perlakukan detail dokumen sebagai apa yang dimasukkan pemegang, bukan sebagai sudah diperiksa. Jika lokasi Anda memerlukan pemeriksaan, minta seseorang melihat kartu aslinya.
  5. Anda boleh hanya menerima pas dari penerbit yang Anda percayai, atau menerima penerbit HTTPS mana pun dan menampilkan "Diverifikasi oleh <domain>".
  6. Jangan pernah meminta aplikasi pemegang lebih dari yang dibawa pas. Pemegang yang memilih apa yang dibagikan.

5. Aturan untuk aplikasi

  1. Buat pas baru setidaknya setiap menit selama pas ditampilkan di layar.
  2. Biarkan pemegang memilih detail opsional mana yang dimasukkan, setiap kali atau sebagai pilihan tersimpan yang dapat mereka ubah.
  3. Jangan pernah memasukkan apa pun yang tidak dipilih pemegang, termasuk pemberi kerja, lokasi, atau id internal mereka.

6. Memeriksa pas dengan JavaScript

Hanya ini yang dibutuhkan kios, cukup menggunakan kriptografi bawaan browser:

async function readPass(text, fetchKeys) {
  const [prefix, body, signature] = text.split('.');
  if (prefix !== 'OSP1') throw new Error('Not a site pass');

  const pass = JSON.parse(atob(body.replace(/-/g, '+').replace(/_/g, '/')));
  const keys = await fetchKeys(pass.issuer); // GET <issuer>/.well-known/open-site-pass/keys.json
  const jwk = keys.find(k => k.keyId === pass.keyId)?.publicKey;

  const key = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
  const fromB64 = s => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
  const ok = await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, fromB64(signature), new TextEncoder().encode(body));

  const now = Date.now(), slack = 2 * 60 * 1000;
  if (!ok || Date.parse(pass.expiresAt) + slack < now) throw new Error('Not valid');
  return pass;
}

Menggunakannya dengan Timeclock.Kiwi

Siapa pun yang masuk ke aplikasi Timeclock.Kiwi dapat menampilkan pas dari Pas Lokasi Saya, dan setiap kios registrasi lokasi Timeclock.Kiwi dapat membacanya, termasuk pas dari aplikasi lain yang mengikuti format ini.

Kami selalu senang membantu.
Hubungi kami dan kami akan berusaha sebaik mungkin agar sistem absensi karyawan kami sesuai untuk Anda.