@samandar/styx-client
v0.1.0
Published
Framework-agnostic client for the Styx local signing agent (PKCS#7). Works with Vue 2, Vue 3 and Nuxt 3.
Maintainers
Readme
@samandar/styx-client
Framework-agnostic client for the Styx local signing agent (http://127.0.0.1:6210/crypto):
list certificates, create PKCS#7/CMS signatures, request certificates.
- No dependencies, ~8 kB, ES2017 output: works in Vue 2.6 + webpack 4 without transpiling
node_modules. - One plugin for Vue 2 (
Vue.use) and Vue 3 (app.use), plain client for Nuxt 3 / anything else. - TypeScript types included.
Agent API reference: AzizParpiyev/styx-example.
Install
npm install @samandar/styx-clientUsage
Plain JS
import { createStyxClient, sortCerts, isCertExpired } from "@samandar/styx-client"
const styx = createStyxClient({ agentUrl: "http://127.0.0.1:6210/crypto" })
const certs = sortCerts(await styx.listCerts()) // valid first
const cert = certs.find((c) => !isCertExpired(c))
const pkcs7 = await styx.sign(cert, challengeFromBackend) // base64 CMS, send it to your backendVue 2.6
// main.js
import Vue from "vue"
import Styx from "@samandar/styx-client"
Vue.use(Styx, { agentUrl: "http://127.0.0.1:6210/crypto" })
// any component
const certs = await this.$styx.listCerts()Vue 3
import { createApp, inject } from "vue"
import Styx from "@samandar/styx-client"
createApp(App).use(Styx, { agentUrl: "http://127.0.0.1:6210/crypto" })
// Options API: this.$styx · Composition API:
const styx = inject("styx")Nuxt 3
// plugins/styx.client.ts — `.client`: the agent runs on the user's machine, never call it during SSR
import { createStyxClient } from "@samandar/styx-client"
export default defineNuxtPlugin(() => ({
provide: { styx: createStyxClient({ agentUrl: useRuntimeConfig().public.styxAgentUrl }) }
}))// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: { public: { styxAgentUrl: "http://127.0.0.1:6210/crypto" } }
})<script setup lang="ts">
const { $styx } = useNuxtApp()
onMounted(async () => { certs.value = await $styx.listCerts() })
</script>API
createStyxClient(options?)
| Option | Default | |
|---|---|---|
| agentUrl | http://127.0.0.1:6210/crypto | Agent base URL |
| timeout | 0 (off) | Request timeout, ms. Signing waits for the user's PIN, keep it generous |
| checkLoopback | true | When a request fails, check Chrome's "apps on device" permission to report LOOPBACK_DENIED |
| fetch | global fetch | Custom fetch |
Returns a client:
| Method | Returns | Agent endpoint |
|---|---|---|
| listCerts() | StyxCert[] | getCertInfo |
| getCertInfo() | raw response | getCertInfo |
| sign(cert, data, { detached?, cosign? }) | base64 CMS | signMSG |
| requestCertificate({ phone, inn, password?, pin?, tokenType? }) | { step: "otp_sent" \| "issued" } | getCertificate |
| request(path, body?) | raw response | any |
requestCertificate is two steps: call it without password (agent sends an SMS code), then again with
password (the SMS code) and pin. tokenType: "virtual" (default), "hard", "ePass".
StyxCert
{
CN, O, OU, PINFL, TIN, // from the subject (uzPINFL / uzINN)
isLegalEntity, // true when uzINN is present
serialNumber, thumbprint, issuer,
validFrom, validTo, // Date
subject, // all parsed subject fields
raw // original certInfos item (incl. pubCert)
}Helpers: parseSubject, normalizeCert, isCertExpired(cert), daysUntilExpiry(cert), sortCerts(certs).
Errors
Every agent failure is a StyxError with a code:
| ERROR_CODES.* | code | Meaning |
|---|---|---|
| UNAVAILABLE | STYX_UNAVAILABLE | Agent not installed / not running, or blocked by CORS |
| LOOPBACK_DENIED | LOOPBACK_DENIED | Request failed and Chrome's "apps on device" permission is denied for the site |
| AGENT_ERROR | STYX_ERROR | HTTP 4xx/5xx or non-success status; message is the agent's text, data the body |
| TIMEOUT | STYX_TIMEOUT | timeout exceeded |
import { isStyxError, ERROR_CODES } from "@samandar/styx-client"
try {
await styx.listCerts()
} catch (e) {
if (isStyxError(e, ERROR_CODES.UNAVAILABLE)) showInstallStyxHint()
else if (isStyxError(e, ERROR_CODES.LOOPBACK_DENIED)) showEnableLocalAppsHint()
else throw e
}Notes
- The Chrome permission is only consulted after a failed request: it can be
deniedwhile requests still succeed (for example when the page itself is served fromlocalhost). - The agent must allow your site's origin (CORS). Check this on your real domain, not only on localhost.
- This package only talks to the local agent. Verifying signatures (STYX-SERVER
VerifyAndGetCmsContent) belongs on your backend.
Development
npm install
npm test # unit tests + tests against the mock agent over real HTTP
npm run build # dist/ (ESM, CJS, d.ts), fails if output is newer than ES2017
npm run mock-agent # fake agent on :6210 for UI work (SMS code: 12345)Integration fixtures (use the packed tarball, like a real install):
npm run build && npm pack
# Vue 2.6 + webpack 4
cd fixtures/vue2-webpack4 && npm i ../../samandar-styx-client-*.tgz && npm i
NODE_OPTIONS=--openssl-legacy-provider npm run build && npm test
# Nuxt 3 (open http://localhost:3000 with `npm run mock-agent` running)
cd fixtures/nuxt3 && npm i ../../samandar-styx-client-*.tgz && npm run build && npm run previewLicense
MIT
