Käsitteet

Mitä Session, Evidence-rivi ja auditointiketju oikeasti ovat, mahdollisimman harvoin sanoin. Lue tämä kerran, ja API-viittaus käy järkeen.

Organisaatio

Ylimmän tason tenantti. Yksi organisaatio vastaa yhtä asiakastiliä. Jokainen muu resurssi (istunnot, todisteet, auditointitapahtumat, käyttäjät) on rajattu organisaatioon row-level securityn kautta taustalla olevissa Postgres-tauluissa. Bugi sovelluskoodissa ei voi ylittää tenantteja — tietokanta kieltäytyy kyselystä.

Organisaatiolla on: jäsenet (roolipohjaisella pääsyllä varustetut käyttäjät), brändäys (logo / värit / PDF-alatunniste), laskutustilaus, valinnainen KYB-oikeushenkilödata, valinnainen SSO-konfiguraatio ja säilytyspolitiikka.

Jäsen, Rooli, Oikeus

Jäsenyys on Käyttäjän ja Organisaation välinen liitos. Käyttäjällä voi olla jäsenyyksiä useissa organisaatioissa ja hän voi vaihtaa niiden välillä (aktiivinen organisaatio kulkee JWT-claimina).

Jokainen organisaatio kylvää neljä järjestelmäroolia luonnissa:

• org_admin — täysi hallinta. Laskutus, jäsenet, brändäys, säilytys.
• inspector — voi tehdä tarkastuksia, kaapata todisteita, allekirjoittaa raportteja.
• observer — vain luku -pääsy istuntoihin + auditointidataan.
• auditor — vain luku -pääsy sekä ketjun todennusoikeus.

Organisaation adminit voivat luoda mukautettuja rooleja kokoamalla oikeusluettelosta. Oikeudet slug-tarkistetaan näkymäkerroksessa + ristiintarkistetaan RLS:llä DB-kerroksessa.

Istunto

Yksi tarkastus. Laskutuksen yksikkö (maksat per suljettu istunto) ja todisteen yksikkö (auditointiketju on istuntokohtainen, ei organisaatiokohtainen).

Istunnolla on: operaattori (tiimisi jäsen, joka aloitti sen), yksi tai useampi osallistuja (kenttäkäyttäjä sekä valinnaiset tarkkailijat), suostumustila, valinnainen GPS-sijainti, valinnaiset muistiinpanot, auditointiketju ja — kun suljettu — TSA-ankkuroidut aikaleimatokenit.

Osallistuja

Yksi henkilö istunnossa. Istunnossa on yksi operaattori ja vähintään yksi kenttäkäyttäjä; valinnaisia lisätarkkailijoita tuetaan. Kenttäkäyttäjät liittyvät kertakäyttöisellä allekirjoitetulla URLilla (ei tiliä vaadita); operaattorit + tarkkailijat ovat organisaation jäseniä.

Todiste

Kaapattu todistuskappale istunnon aikana. Lajit:

• snapshot — still-kuva kenttäkäyttäjän kamerasta.
• annotation — piirros tilannekuvan tai taulun päällä.
• whiteboard — istunnonaikainen Excalidraw-kanvas vietynä PNG:nä + tilana.
• clip — lyhyt videopätkä.
• document — ladattu tiedosto (chat-kerroksen käyttämä PDF-allekirjoitusta varten).

Jokaisella Evidence-rivillä on binäärisisältönsä SHA-256, tallennettuna auditointiketjuun. Tiedoston peukalointi jälkikäteen kaataa todentamisen.

Auditointiketju

Kryptografinen selkäranka. Jokainen istunnon tapahtuma — istunnon luonti, suostumuksen anto, GPS-tallennus, todisteen kaappaus, annotaatio, taulun tallennus, allekirjoitus, istunnon päättyminen — luo AuditEvent -rivin, jossa on:

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

Ensimmäinen tapahtuma käyttää prev_hash = "0" * 64 (genesis). Jokainen seuraava tapahtuma käyttää edellisen tapahtuman hashia arvona prev_hash ja kasvattaa arvoa sequence yhdellä. Postgres-advisory lock sarjoittaa kirjoitukset istunnoittain; vain lisäävä trigger estää taulun UPDATE- ja DELETE-operaatiot.

TimestampToken (TSA-ankkuri)

Istunnon päättyessä (ja operaattorin laukaisemassa "leimaa nyt" -toiminnossa) nykyinen ketjun pää lähetetään kolmelle riippumattomalle aikaleimaviranomaiselle:

• YodaLedger — Tezos-lohkoketjuankkuri. ~15–20 minuutin lopullisuus. Asynkroninen; saamme callbackin, kun lohko vahvistetaan.
• FreeTSA — RFC 3161 -aikaleima. Synkroninen; token palautetaan välittömästi. Vaihdettavissa maksulliseen QTSP:hen (DataSure) eIDAS Art. 42 -yhteensopivuutta varten.
• OpenTimestamps — Bitcoin-ankkuri OpenTimestamps-kalenteriprotokollan kautta. Asynkroninen; päivityspolku ajetaan Celery-sweepillä.

Kolme on tarkoituksellista — jos jokin yksittäinen TSA katoaa, kaksi muuta ankkuroivat silti ketjun. Tarkastaja voi todentaa mitä tahansa niistä vasten riippumattomasti julkisilla lohkoselaimilla / verify-endpointeilla.

Allekirjoitus (SES / AES / QES)

Kolme eIDAS-tasoa, kaikki samalla audit-raportti-PDF:llä:

• SES (Yksinkertainen sähköinen allekirjoitus) — auditointiketjuun tukeutuva, ei allekirjoitusvarmennetta. Sopii sisäisiin tietueisiin.
• AES (Kehittynyt sähköinen allekirjoitus) — henkilöllisyyteen sidottu allekirjoitusvarmenne, PAdES B-T -ankkuroitu. Sopii useimpiin B2B-sopimuksiin.
• QES (Kvalifioitu sähköinen allekirjoitus) — korkein eIDAS-taso, käsin kirjoitetun allekirjoituksen oikeudellinen vastine koko EU:ssa. Vaatii antajaorganisaation KYB-todentamisen.

Kampanja (valinnainen)

Istuntojen looginen ryhmittely eräraportointia varten — "Q2 2026 ajoneuvokorvaukset" tai "Kohde A luovutusviat". Istunnot eivät vaadi kampanjaa; se on raportointimukavuus.

Webhook

Asiakkaan rekisteröimä URL, joka vastaanottaa HMAC-allekirjoitettuja tapahtuma-POSTeja. Tapahtumatyypit: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, sekä webhook.test toimituksen varmennukseen.

Allekirjoitus: Stripe-tyylinen t=...,v1=... -otsake HMAC-SHA256:lla kohteesta <timestamp>.<body>. SDK:n constructEvent() -apufunktio varmentaa vakioajassa 5 minuutin kellonpoikkeamatoleranssilla.