Piekļūstiet sava seifa saturam programmatiski ar zero-knowledge šifrēšanu.
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).
Atšifrēšanas atslēga nekad netiek nosūtīta uz serveri
Pilnīga tipu atbalsts un IntelliSense
Intuitīvs API ar kļūdu apstrādi
Instalējiet SDK ar npm, yarn vai pnpm
npm install @vairogs/sdkyarn add @vairogs/sdkpnpm add @vairogs/sdkIzveidojiet klientu un sāciet izmantot API
Nepieciešamas Tag API atslēgas
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',
});VairogsClient konstruktora parametri
| Parametrs | Tips | Apraksts |
|---|---|---|
accessKey* | string | Tag API piekļuves atslēga (vgtk_a_xxx) - tiek nosūtīta serverim autentifikācijai |
decryptKey* | string | Tag API atšifrēšanas atslēga (vgtk_d_xxx) - NEKAD netiek nosūtīta, izmanto lokāli |
baseUrl | string | API bāzes URL (default: 'https://vairogs.lv') |
timeout | number | Request timeout milisekundēs (default: 30000) |
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
Metodes datu iegūšanai un atšifrēšanai
// 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 ikonaimport { 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 });// 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 datiSDK piedāvā ērtības metodes, kas automātiski iegūst un atšifrē ierakstus:
// 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}`);
}Jaunu ierakstu izveide ar automātisku šifrēšanu
await client.createPassword({
title: 'GitHub',
username: 'myuser',
password: 'secret123',
url: 'https://github.com',
notes: 'Mans GitHub konts (optional)',
});await client.createNote({
title: 'Svarīgi dati',
content: 'Šeit ir mana konfidenciāla informācija...',
});await client.createTotp({
title: 'GitHub 2FA',
secret: 'JBSWY3DPEHPK3PXP',
issuer: 'GitHub',
account: 'myuser@example.com',
});Attēlu un dokumentu augšupielāde un lejupielāde
Node.js vide
Buffer un fs moduli. Pārliecinieties, ka strādājat Node.js vidē, nevis pārlūkprogrammā.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)',
});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)',
});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);Esošo ierakstu atjaunināšana un dzēšana
// 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ēsiet ierakstu pēc ID
await client.deleteItem(itemId);
console.log('Ieraksts veiksmīgi dzēsts');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.
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',
};Visu iespējamo kļūdu apstrāde
SDK met trīs galvenos kļūdu tipus, kurus Jūs varat apstrādāt:
VairogsApiErrorAPI kļūdas (autentifikācijas kļūdas, nederīgi parametri, servera kļūdas)
VairogsCryptoErrorKriptogrāfijas kļūdas (atšifrēšanas kļūdas, nederīgas atslēgas)
VairogsErrorVispārējas kļūdas (tīkla kļūdas, timeout, utt.)
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);
}
}Kā darbojas zero-knowledge šifrēšana
Zero-Knowledge Garantija
vgtk_a_xxxTiek 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_xxxNEKAD 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.
Atšifrēšanas atslēga + PBKDF2 (100k iterācijas) → X25519 keypair
Jūsu dati → AES-256-GCM ar random DEK → Šifrēts saturs
DEK → NaCl box (X25519 + XSalsa20-Poly1305) → Wrapped DEK
Tikai šifrētie dati un wrapped DEK tiek nosūtīti uz serveri
Lejupielādē → Unwrap DEK ar X25519 → Atšifrē ar AES-256-GCM
| Parametrs | Vērtība |
|---|---|
| PBKDF2 Iterācijas | 100,000 |
| Key Derivation Salt | vairogs-mcp-key-derivation-v1 |
| Datu Šifrēšana | AES-256-GCM |
| IV Izmērs | 12 bytes |
| Auth Tag Izmērs | 16 bytes |
| DEK Wrapping | NaCl box (X25519 + XSalsa20-Poly1305) |
Tiešā piekļuve crypto utilītēm
Progresīviem lietotājiem SDK eksportē crypto utilītes tiešai izmantošanai:
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
Visa SDK funkcionalitāte vienā skriptā
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();Papildu informācija un atbalsts
Izveidojiet Tag API atslēgas savā Vairogs.lv kontā un sāciet izmantot SDK!