Izstrādātājiem & AI

Vairogs API & MCP

Piekļūstiet sava seifa saturam programmatiski ar zero-knowledge šifrēšanu.

SDK & CLI

TypeScript SDK Tag API v2 izmantošanai

Oficiālais TypeScript SDK Vairogs.lv Tag API v2, kas nodrošina zero-knowledge šifrēšanu ar divslēdžu arhitektūru. Ideāls risinājums integrācijām ar Node.js, TypeScript projektiem un AI asistentiem (MCP).

Zero-Knowledge

Atšifrēšanas atslēga nekad netiek nosūtīta uz serveri

TypeScript

Pilnīga tipu atbalsts un IntelliSense

Vienkārši lietot

Intuitīvs API ar kļūdu apstrādi

Instalācija

Instalējiet SDK ar npm, yarn vai pnpm

bash
npm install @vairogs/sdk
bash
yarn add @vairogs/sdk
bash
pnpm add @vairogs/sdk

Ātrā Sākšana

Izveidojiet klientu un sāciet izmantot API

Nepieciešamas Tag API atslēgas

Lai izmantotu SDK, Jums nepieciešams izveidot Tag API atslēgas savā Vairogs.lv kontā. Dodieties uz Iestatījumi → Tag API un izveidojiet jaunu atslēgu pāri.
typescript
import { VairogsClient } from '@vairogs/sdk';

// Inicializējiet klientu ar abām atslēgām
const client = new VairogsClient({
  accessKey: 'vgtk_a_xxx',    // Piekļuves atslēga (tiek nosūtīta serverim)
  decryptKey: 'vgtk_d_xxx',   // Atšifrēšanas atslēga (NEKAD netiek nosūtīta)
  baseUrl: 'https://vairogs.lv' // Optional, default ir vairogs.lv
});

// Iegūstiet un atšifrējiet visas paroles
const passwords = await client.listPasswords();

// Izvadiet visas paroles
for (const item of passwords) {
  console.log(`${item.title}: ${item.data.username}`);
}

// Izveidojiet jaunu paroli
await client.createPassword({
  title: 'GitHub',
  username: 'myuser',
  password: 'secret123',
  url: 'https://github.com',
  notes: 'Mans GitHub konts',
});

Konfigurācija

VairogsClient konstruktora parametri

ParametrsTipsApraksts
accessKey*stringTag API piekļuves atslēga (vgtk_a_xxx) - tiek nosūtīta serverim autentifikācijai
decryptKey*stringTag API atšifrēšanas atslēga (vgtk_d_xxx) - NEKAD netiek nosūtīta, izmanto lokāli
baseUrlstringAPI bāzes URL (default: 'https://vairogs.lv')
timeoutnumberRequest timeout milisekundēs (default: 30000)
typescript
const client = new VairogsClient({
  accessKey: process.env.VAIROGS_ACCESS_KEY!,
  decryptKey: process.env.VAIROGS_DECRYPT_KEY!,
  baseUrl: 'https://vairogs.lv',
  timeout: 60000 // 60 sekundes
});

Drošība

Nekad neglabājiet atslēgas tieši kodā! Izmantojiet vides mainīgos (.env fails) un pievienojiet .env failam .gitignore, lai izvairītos no nejauša atslēgu publicēšanas.

Datu Lasīšana

Metodes datu iegūšanai un atšifrēšanai

Iegūt Tag informāciju

typescript
// Iegūstiet informāciju par Tag (nosaukums, ikona, utt.)
const info = await client.getInfo();
console.log(info.name); // Tag nosaukums
console.log(info.icon); // Tag ikona

Visu ierakstu saraksts

typescript
import { ItemType } from '@vairogs/sdk';

// Iegūstiet visus ierakstus (šifrētus)
const allItems = await client.listItems();

// Filtrējiet pēc tipa
const passwords = await client.listItems({ type: ItemType.PASSWORD });
const notes = await client.listItems({ type: ItemType.NOTE });
const totps = await client.listItems({ type: ItemType.TOTP });

Atšifrēt atsevišķu ierakstu

typescript
// Iegūstiet šifrētu ierakstu
const items = await client.listItems();
const firstItem = items[0];

// Atšifrējiet to
const decrypted = await client.decryptItem(firstItem);
console.log(decrypted.title);
console.log(decrypted.data); // Atšifrētie dati

Ērtības metodes (list + decrypt)

SDK piedāvā ērtības metodes, kas automātiski iegūst un atšifrē ierakstus:

typescript
// Visas paroles (atšifrētas)
const passwords = await client.listPasswords();
for (const pwd of passwords) {
  console.log(`${pwd.title}: ${pwd.data.username}@${pwd.data.url}`);
}

// Visas piezīmes (atšifrētas)
const notes = await client.listNotes();
for (const note of notes) {
  console.log(`${note.title}: ${note.data.content}`);
}

// Visi TOTP (atšifrēti)
const totps = await client.listTotps();
for (const totp of totps) {
  console.log(`${totp.title}: ${totp.data.secret}`);
}

Datu Rakstīšana

Jaunu ierakstu izveide ar automātisku šifrēšanu

Izveidot paroli

typescript
await client.createPassword({
  title: 'GitHub',
  username: 'myuser',
  password: 'secret123',
  url: 'https://github.com',
  notes: 'Mans GitHub konts (optional)',
});

Izveidot piezīmi

typescript
await client.createNote({
  title: 'Svarīgi dati',
  content: 'Šeit ir mana konfidenciāla informācija...',
});

Izveidot TOTP (2FA)

typescript
await client.createTotp({
  title: 'GitHub 2FA',
  secret: 'JBSWY3DPEHPK3PXP',
  issuer: 'GitHub',
  account: 'myuser@example.com',
});

Failu Operācijas

Attēlu un dokumentu augšupielāde un lejupielāde

Node.js vide

Failu operācijas izmanto Node.js Buffer un fs moduli. Pārliecinieties, ka strādājat Node.js vidē, nevis pārlūkprogrammā.

Augšupielādēt attēlu

typescript
import fs from 'fs';

// Nolasiet attēlu no diska
const imageBuffer = fs.readFileSync('./photo.jpg');

// Augšupielādējiet ar automātisku sīktēla ģenerēšanu
await client.uploadImage({
  title: 'Mana fotogrāfija',
  file: imageBuffer,
  fileName: 'photo.jpg',
  mimeType: 'image/jpeg',
  notes: 'Atvaļinājuma foto (optional)',
});

Augšupielādēt dokumentu

typescript
import fs from 'fs';

// Nolasiet dokumentu no diska
const docBuffer = fs.readFileSync('./contract.pdf');

// Augšupielādējiet
await client.uploadDocument({
  title: 'Līgums 2025',
  file: docBuffer,
  fileName: 'contract.pdf',
  mimeType: 'application/pdf',
  notes: 'Darba līgums (optional)',
});

Lejupielādēt un atšifrēt failu

typescript
import fs from 'fs';

// Lejupielādējiet oriģinālo failu (atšifrēts)
const fileBuffer = await client.downloadFile(itemId);
fs.writeFileSync('./downloaded-file.jpg', fileBuffer);

// Lejupielādējiet sīktēlu (tikai attēliem)
const thumbnailBuffer = await client.downloadFile(itemId, 'thumbnail');
fs.writeFileSync('./thumbnail.jpg', thumbnailBuffer);

Labošana un Dzēšana

Esošo ierakstu atjaunināšana un dzēšana

Labot ierakstu

typescript
// Atjauniniet paroli
await client.updateItem(itemId, {
  title: 'Jauns nosaukums',
  data: {
    username: 'newuser',
    password: 'newsecret',
    url: 'https://example.com',
  }
});

// Atjauniniet tikai atsevišķus laukus
await client.updateItem(itemId, {
  title: 'Atjaunināts nosaukums'
  // data paliek nemainīts
});

Dzēst ierakstu

typescript
// Dzēsiet ierakstu pēc ID
await client.deleteItem(itemId);

console.log('Ieraksts veiksmīgi dzēsts');
Dzēšana ir neatgriezeniska! Pārliecinieties, ka tiešām vēlaties dzēst ierakstu.

TypeScript Tipi

SDK ietver pilnīgu tipu atbalstu

SDK eksportē visus nepieciešamos TypeScript tipus, lai nodrošinātu tipu drošību un IntelliSense atbalstu Jūsu IDE.

typescript
import {
  VairogsClient,
  VairogsError,
  VairogsApiError,
  VairogsCryptoError,
  ItemType,
  TagApiItem,
  DecryptedItem,
  PasswordData,
  NoteData,
  TotpData,
} from '@vairogs/sdk';

// Visi tipi ir pieejami ar pilnu IntelliSense atbalstu
const client: VairogsClient = new VairogsClient({ ... });

// Item tipi
const item: TagApiItem = { ... };
const decrypted: DecryptedItem<PasswordData> = await client.decryptItem(item);

// Datu tipi
const passwordData: PasswordData = {
  username: 'user',
  password: 'pass',
  url: 'https://example.com',
};

Kļūdu Apstrāde

Visu iespējamo kļūdu apstrāde

SDK met trīs galvenos kļūdu tipus, kurus Jūs varat apstrādāt:

VairogsApiError

API kļūdas (autentifikācijas kļūdas, nederīgi parametri, servera kļūdas)

VairogsCryptoError

Kriptogrāfijas kļūdas (atšifrēšanas kļūdas, nederīgas atslēgas)

VairogsError

Vispārējas kļūdas (tīkla kļūdas, timeout, utt.)

typescript
import {
  VairogsError,
  VairogsApiError,
  VairogsCryptoError
} from '@vairogs/sdk';

try {
  const passwords = await client.listPasswords();
  console.log('Paroles iegūtas veiksmīgi!');
} catch (error) {
  if (error instanceof VairogsApiError) {
    // API kļūda
    console.error(`API kļūda: ${error.code} (HTTP ${error.statusCode})`);
    console.error(`Ziņojums: ${error.message}`);

    if (error.statusCode === 401) {
      console.error('Nederīgas API atslēgas!');
    } else if (error.statusCode === 403) {
      console.error('Nav piekļuves tiesību!');
    }
  } else if (error instanceof VairogsCryptoError) {
    // Kriptogrāfijas kļūda
    console.error(`Crypto kļūda: ${error.code}`);
    console.error('Iespējams, nederīga atšifrēšanas atslēga');
  } else if (error instanceof VairogsError) {
    // Vispārēja kļūda
    console.error(`Kļūda: ${error.code}`);
    console.error(`Ziņojums: ${error.message}`);
  } else {
    // Nezināma kļūda
    console.error('Nezināma kļūda:', error);
  }
}

Divslēdžu Arhitektūra

Kā darbojas zero-knowledge šifrēšana

Zero-Knowledge Garantija

Vairogs serveris NEKAD neredz Jūsu atšifrēšanas atslēgu vai atšifrētus datus. Visa šifrēšana un atšifrēšana notiek lokāli Jūsu ierīcē.
vgtk_a_xxx

Piekļuves Atslēga

Tiek nosūtīta serverim katru reizi, lai autentificētu API pieprasījumu. Dod piekļuvi Jūsu Tag datiem (šifrētā formātā).

vgtk_d_xxx

Atšifrēšanas Atslēga

NEKAD netiek nosūtīta serverim! Izmanto lokāli, lai atvasinātu X25519 keypair un atšifrētu datus. Tikai Jūs zināt šo atslēgu.

Kā tas darbojas?

1

Atslēgu Derivācija

Atšifrēšanas atslēga + PBKDF2 (100k iterācijas) → X25519 keypair

2

Datu Šifrēšana

Jūsu dati → AES-256-GCM ar random DEK → Šifrēts saturs

3

DEK Wrap

DEK → NaCl box (X25519 + XSalsa20-Poly1305) → Wrapped DEK

4

Nosūtīšana

Tikai šifrētie dati un wrapped DEK tiek nosūtīti uz serveri

5

Atšifrēšana

Lejupielādē → Unwrap DEK ar X25519 → Atšifrē ar AES-256-GCM

Kriptogrāfiskie Parametri

ParametrsVērtība
PBKDF2 Iterācijas100,000
Key Derivation Saltvairogs-mcp-key-derivation-v1
Datu ŠifrēšanaAES-256-GCM
IV Izmērs12 bytes
Auth Tag Izmērs16 bytes
DEK WrappingNaCl box (X25519 + XSalsa20-Poly1305)

Progresīva Lietošana

Tiešā piekļuve crypto utilītēm

Progresīviem lietotājiem SDK eksportē crypto utilītes tiešai izmantošanai:

typescript
import {
  deriveKeypairFromDecryptKey,
  generateDEK,
  aesEncrypt,
  aesDecrypt,
  wrapDEK,
  unwrapDEK,
  CRYPTO_CONSTANTS,
} from '@vairogs/sdk';

// Atvasināt keypair manuāli
const keypair = await deriveKeypairFromDecryptKey('vgtk_d_xxx');
console.log('Public key:', keypair.publicKey);
console.log('Secret key:', keypair.secretKey);

// Ģenerēt random DEK
const dek = generateDEK();

// Šifrēt/atšifrēt manuāli
const encrypted = await aesEncrypt('slepeni dati', dek);
const decrypted = await aesDecrypt(encrypted, dek);

// Wrap/unwrap DEK
const wrapped = wrapDEK(dek, keypair, recipientPublicKey);
const unwrapped = unwrapDEK(wrapped, keypair, senderPublicKey);

// Konstantes
console.log(CRYPTO_CONSTANTS.PBKDF2_ITERATIONS); // 100000
console.log(CRYPTO_CONSTANTS.SALT); // 'vairogs-mcp-key-derivation-v1'

Tikai progresīviem lietotājiem

Tiešā crypto utilītu izmantošana prasa dziļas zināšanas kriptogrāfijā. Lielākajā daļā gadījumu izmantojiet augsta līmeņa metodes (createPassword, listPasswords, utt.).

Pilnīgs Piemērs

Visa SDK funkcionalitāte vienā skriptā

typescript
import { VairogsClient, VairogsApiError } from '@vairogs/sdk';
import fs from 'fs';

async function main() {
  // 1. Inicializējiet klientu
  const client = new VairogsClient({
    accessKey: process.env.VAIROGS_ACCESS_KEY!,
    decryptKey: process.env.VAIROGS_DECRYPT_KEY!,
  });

  try {
    // 2. Iegūstiet Tag informāciju
    const info = await client.getInfo();
    console.log(`Tag: ${info.name}`);

    // 3. Izveidojiet jaunu paroli
    await client.createPassword({
      title: 'Test Login',
      username: 'test@example.com',
      password: 'secret123',
      url: 'https://example.com',
    });
    console.log('Parole izveidota!');

    // 4. Iegūstiet visas paroles
    const passwords = await client.listPasswords();
    console.log(`Pavisam paroļu: ${passwords.length}`);

    for (const pwd of passwords) {
      console.log(`- ${pwd.title}: ${pwd.data.username}@${pwd.data.url}`);
    }

    // 5. Izveidojiet piezīmi
    await client.createNote({
      title: 'Test Note',
      content: 'This is a test note',
    });
    console.log('Piezīme izveidota!');

    // 6. Augšupielādējiet attēlu
    const imageBuffer = fs.readFileSync('./test.jpg');
    await client.uploadImage({
      title: 'Test Image',
      file: imageBuffer,
      fileName: 'test.jpg',
      mimeType: 'image/jpeg',
    });
    console.log('Attēls augšupielādēts!');

    // 7. Iegūstiet visus ierakstus
    const allItems = await client.listItems();
    console.log(`Pavisam ierakstu: ${allItems.length}`);

    // 8. Lejupielādējiet pirmo attēlu
    const imageItems = allItems.filter(i => i.type === 'IMAGE');
    if (imageItems.length > 0) {
      const downloaded = await client.downloadFile(imageItems[0].id);
      fs.writeFileSync('./downloaded.jpg', downloaded);
      console.log('Attēls lejupielādēts!');
    }

  } catch (error) {
    if (error instanceof VairogsApiError) {
      console.error(`API Error: ${error.code} (HTTP ${error.statusCode})`);
    } else {
      console.error('Error:', error);
    }
  }
}

main();

Gatavs sākt?

Izveidojiet Tag API atslēgas savā Vairogs.lv kontā un sāciet izmantot SDK!