eimzo-ts 0.1.1 → 0.1.3

package/skills/eimzo-ts/references/examples.md

@@ -0,0 +1,150 @@
+# eimzo-ts examples
+
+All snippets assume one shared instance:
+
+```ts
+// eimzo.ts
+import { createEimzo, createFetchBackend, DEV_API_KEYS } from 'eimzo-ts';
+
+export const eimzo = createEimzo({
+  apiKeys: { ...DEV_API_KEYS },
+  backend: createFetchBackend({
+    challengeUrl: '/api/eimzo/challenge',
+    loginUrl: '/api/eimzo/login',
+    timestampUrl: '/api/eimzo/timestamp',
+  }),
+});
+```
+
+## Key picker data
+
+```ts
+const keys = await eimzo.listKeys();
+const options = keys.map((k, i) => ({
+  value: i,
+  label: `${k.CN} — ${k.TIN || k.PINFL}${k.O ? `, ${k.O}` : ''}`,
+  disabled: k.expired,
+}));
+```
+
+## Login
+
+```ts
+import { isEimzoError, type EimzoKey } from 'eimzo-ts';
+
+async function loginWith(key: EimzoKey) {
+  try {
+    const user = await eimzo.login(key); // whatever your /api/eimzo/login returns
+    return user;
+  } catch (e) {
+    if (isEimzoError(e, 'CANCELLED')) return null;
+    throw new Error(eimzo.t(e));
+  }
+}
+```
+
+## Sign a document with a timestamp and send it
+
+```ts
+await eimzo.loadKey(key); // once; later signatures reuse the keyId
+const pkcs7 = await eimzo.signDocument(JSON.stringify({ id: docId, nonce: crypto.randomUUID(), body }));
+await fetch(`/api/documents/${docId}/sign`, { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: pkcs7 });
+```
+
+Put a unique ID into the signed content so the backend can reject a replayed signature.
+
+## Sign a file (detached)
+
+```ts
+const file = input.files![0];
+const pkcs7 = await eimzo.signFile(file, { maxSize: 20 * 1024 * 1024 });
+// send both the file and pkcs7; the backend verifies with /backend/pkcs7/verify/detached
+```
+
+## Logout
+
+```ts
+await eimzo.unloadKey();
+```
+
+## Angular service
+
+```ts
+import { Injectable } from '@angular/core';
+import { createEimzo, createFetchBackend, DEV_API_KEYS } from 'eimzo-ts';
+
+@Injectable({ providedIn: 'root' })
+export class EimzoService {
+  readonly client = createEimzo({
+    apiKeys: { ...DEV_API_KEYS },
+    backend: createFetchBackend({ challengeUrl: '/api/eimzo/challenge', loginUrl: '/api/eimzo/login' }),
+  });
+}
+```
+
+To reuse `HttpClient` interceptors, pass a custom backend:
+
+```ts
+backend: {
+  getChallenge: () => firstValueFrom(this.http.get<{ challenge: string }>('/api/eimzo/challenge')).then((r) => r.challenge),
+  login: (pkcs7) => firstValueFrom(this.http.post('/api/eimzo/login', pkcs7, { headers: { 'Content-Type': 'text/plain' } })),
+}
+```
+
+## React
+
+```tsx
+import { useEffect, useState } from 'react';
+import type { EimzoKey } from 'eimzo-ts';
+import { eimzo } from './eimzo';
+
+export function KeyPicker({ onPick }: { onPick: (k: EimzoKey) => void }) {
+  const [keys, setKeys] = useState<EimzoKey[]>([]);
+  const [error, setError] = useState<string>();
+  useEffect(() => { eimzo.listKeys().then(setKeys, (e) => setError(eimzo.t(e))); }, []);
+  if (error) return <p role="alert">{error}</p>;
+  return (
+    <ul>
+      {keys.map((k) => (
+        <li key={k.serialNumber}>
+          <button disabled={k.expired} onClick={() => onPick(k)}>{k.CN} — {k.TIN || k.PINFL}</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+In Next.js, put this in a `'use client'` component.
+
+## Vue
+
+```ts
+import { onMounted, ref } from 'vue';
+import type { EimzoKey } from 'eimzo-ts';
+import { eimzo } from './eimzo';
+
+const keys = ref<EimzoKey[]>([]);
+onMounted(async () => { keys.value = await eimzo.listKeys(); });
+```
+
+## Unit test with a fake transport
+
+```ts
+import { createEimzo } from 'eimzo-ts';
+
+const eimzo = createEimzo({
+  transport: async (req) => {
+    const name = req.plugin ? `${req.plugin}.${req.name}` : req.name;
+    switch (name) {
+      case 'version': return { success: true, major: '6', minor: '3' };
+      case 'pfx.list_all_certificates': return { success: true, certificates: [] };
+      case 'pfx.load_key': return { success: true, keyId: 'K1' };
+      case 'pkcs7.create_pkcs7': return { success: true, pkcs7_64: 'MIAG...' };
+      default: return { success: false, reason: `not mocked: ${name}` };
+    }
+  },
+});
+```
+
+Simulate the user cancelling: `{ success: false, status: -5000, reason: 'Ввод пароля отменен' }` → `CANCELLED`.

package/skills/eimzo-ts/references/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting eimzo-ts
+
+Read `error.code` first, then `error.reason` / `error.status` (raw E-IMZO data) or `error.httpStatus` (backend).
+
+| code | Typical cause | Fix |
+|---|---|---|
+| `NOT_INSTALLED` | E-IMZO is not running or not installed; the WebSocket to 127.0.0.1 closed. `wsCode` has the close code. | Ask the user to start E-IMZO or install it from https://e-imzo.uz/main/downloads/. |
+| `WEBSOCKET_UNSUPPORTED` | No `WebSocket` (very old browser, or code ran on the server during SSR). | Run on the client only; in Node pass `WebSocketImpl`. |
+| `TIMEOUT` | `timeoutMs` is set and E-IMZO (or the user) did not answer in time. | Raise or remove `timeoutMs`. |
+| `OUTDATED_VERSION` | Installed E-IMZO is older than `minVersion` (default 4.86). | Ask the user to update E-IMZO. |
+| `API_KEY_REJECTED` | No valid API key for the page's domain. | `DEV_API_KEYS` for localhost; "Developer mode" in the E-IMZO tray for test domains; an issued key per production domain/subdomain. |
+| `WRONG_PASSWORD` | Wrong key password. `reason` "Password is not ASCII" means a non-Latin keyboard layout. | Let the user retry. E-IMZO itself already showed a message. |
+| `CANCELLED` | The user pressed "Cancel" (status -5000). | Do nothing or reset the UI. Do not show an error. |
+| `KEY_NOT_FOUND` | E-IMZO forgot the `keyId` (status -1010/-1014): restart, 24 h, or unloaded. With `autoReloadKey` (default) `sign()` retries once. | Call `loadKey()` again. |
+| `KEY_NOT_LOADED` | `sign`/`signFile`/`signDocument` before `loadKey()`. | Fix the calling code. `login()` loads the key itself. |
+| `FILE_TOO_LARGE` | File larger than `maxSize` (10 MB default). | Raise `maxSize` or reject the file. |
+| `BACKEND_NOT_CONFIGURED` | `login()` without `getChallenge`/`login`, or `signDocument()` without `timestamp`. | Configure `backend`. |
+| `BACKEND_ERROR` | Backend returned non-2xx or `status !== 1`. | Inspect `httpStatus`, `params.detail`; see backend statuses below. |
+| `EIMZO_ERROR` | Anything else from E-IMZO; status 0 with "Функция не найдена" = unknown function or outdated E-IMZO. | Read `reason`. |
+
+## Other symptoms
+
+- **Password asked on every signature.** Several `Eimzo` instances, or `loadKey()` before each `sign()`.
+  Keep one instance and load the key once. Without "Remember for 6 hours" E-IMZO keeps the password 1 minute.
+- **Fewer keys than in E-IMZO.** Keys without TIN and PINFL are skipped by design.
+- **Works on localhost, fails on the real domain.** Missing API key for that domain, or the page is https and
+  E-IMZO's `wss://127.0.0.1:64443` is not reachable.
+
+## e-imzo-server `/backend/auth` statuses
+
+| status | Meaning | Action |
+|---|---|---|
+| 1 | OK | Find the user by PINFL (`1.2.860.3.16.1.2`) or TIN (`1.2.860.3.16.1.1`, else `UID`). |
+| -1 | Certificate status could not be checked (often VPN down) | HTTP 503, ask to retry later; do not log in. |
+| -5 | Signing time outside the allowed window | Ask the user to fix the computer clock. |
+| -10 | Invalid signature | 401 |
+| -11, -12 | Certificate invalid (at signing time) | 401 |
+| -20 | Challenge not found or expired (TTL 120 s) | Restart login. |
+| -24, -25 | Certificate policy / CA not allowed | 401 |