Submit, track, cancel, and verify — the safe public contract.

Install#

The package provides the JavaScript library and the weles-skarbiec-acquire executable. Until an immutable package release is published, pin the Git commit used by a deployment. The minimum public contract is 0.1.0.

git clone https://github.com/wisent-ai/weles-client
npm install --global ./weles-client

Construct a client#

import { WelesClient } from '@wisent-ai/weles-client';

const client = new WelesClient({
  endpoint: process.env.WELES_API_BASE,
  bearer: process.env.WELES_TOKEN,
  organizationId: process.env.WISENT_ORGANIZATION_ID,
  allowedOrigins: ['https://console.example.com'],
  allowedActions: ['export-approved-report'],
  receiptKeys: {
    'current-signing-key': process.env.WELES_RECEIPT_PUBLIC_KEY,
  },
});

Submit, read, cancel#

• submit sends schema weles.task.current with organization ID, normalized origin, exact action, non-secret input, opaque credential refs, evidence policy, justification, Idempotency-Key, and bearer headers. If no key is supplied, the client generates a UUID.
• get performs an exact task-status read; there is no list or search surface.
• cancel submits one explicit cancellation with a required reason; the library never retries, and ambiguous transport outcomes surface as transport-failed.

const accepted = await client.submit({
  origin: 'https://console.example.com',
  action: 'export-approved-report',
  input: { report: 'monthly' },
  credentialRefs: ['customer-console-account'],
  evidencePolicy: 'receipt',
  justification: 'Export authorized by the account owner.',
}, { idempotencyKey: 'caller-retained-operation-id' });

const current = await client.get(accepted.taskId);

const cancelled = await client.cancel(taskId, {
  reason: 'The account owner withdrew approval.',
  idempotencyKey: 'caller-retained-cancellation-id',
});

Verify a receipt offline#

Verification binds taskId, organizationId, origin, action, outcome, evidenceDigest, and the trusted keyId. Store the signed payload, signature, key ID, verified claims, and key-set version together. Obtain keys through a separately authenticated channel — never from the receipt itself.

import { verifyReceipt } from '@wisent-ai/weles-client';

const claims = verifyReceipt(receipt, {
  'current-signing-key': process.env.WELES_RECEIPT_PUBLIC_KEY,
});

Errors and redaction#

Every validation, transport, response, and receipt failure throws WelesClientError with a stable code. Non-2xx bodies are recursively redacted where object keys look sensitive; redaction inspects key names only, not free-form strings, so treat all service errors as potentially sensitive. The library never logs on its own.

Skarbiec credential bridge#

The installed package also provides weles-skarbiec-acquire, the bridge Skarbiec invokes for credential operations against Weles-managed items (acquire, adopt, rotate, reset, verify, remove). Point SKARBIEC_WELES_CREDENTIAL_COMMAND at bin/weles-skarbiec-acquire.mjs inside the installed package.

• The API base resolves only from the Stado forward directory (STADO_FORWARDS_DIR, default ~/.stado/forwards), file weles-admission.local — exactly one line holding the URL. WELES_URL is removed: a missing file, symlink, loosened mode, foreign owner, extra lines, or non-loopback plaintext URL fails as needs_configuration with code WELES_ENDPOINT_UNRESOLVED, phase admission.
• Requests must use the fixed skarbiec.credential-operation.v3 schema; v1 and v2 are rejected with no alias.
• mode submit binds its request ID to the Weles idempotency key and submits the allowlisted skarbiec_credential_acquire action; mode resume requires approval_id (at most 64 characters of [A-Za-z0-9._-]) and resume_token (at most 128); mode status performs only a GET for the returned action-log ID.
• Microsoft Entra operations pin one directory identity each (provider microsoft_entra, field password); mismatches fail with ENTRA_IDENTITY_CONTRACT_MISMATCH before Weles is contacted.
• The bridge never accepts credential material on stdin nor returns credential or task payload material on stdout.