Skip to content

JavaScript SDK

@kiunke.dev/revoked is a typed client for this API. It runs on Node 20 or later, Deno, Bun, edge runtimes and browsers. It has no runtime dependencies, and uses only fetch and WebCrypto. Every request in this section of the documentation has an SDK method. Calls that only the Revoked app makes, such as passkey sign-in or consent screens, are left out on purpose. The package lists each of them, with the reason, in coverage.json.

npm install @kiunke.dev/revoked

A first script

An API key with Manage vault for one section and Manage shares is enough to store a value and share it. Saved as share.mjs and run with node --env-file=.env share.mjs, where .env holds REVOKED_API_KEY:

import { Revoked } from '@kiunke.dev/revoked';

const revoked = new Revoked({ server: 'https://api.example.com', apiKey: process.env.REVOKED_API_KEY });

const record = await revoked.vault.create({ key: 'wifi_password', label: 'Wi-Fi password', value: 'correct-horse' });
const link = await revoked.links.create({ label: 'Wi-Fi for guests', records: [record.id], maxViews: 5 });

console.log(revoked.links.url(link));

The printed address opens the share in a browser. Changing the record changes what the share shows on its next read; revoked.links.revoke(link.id) ends it.

Credentials

A client acts with at most one credential. Each credential travels in its own header, as described in Authentication.

Option Header Use
apiKey X-API-Key Scripts and integrations of the workspace's own
connection X-Revoked-Connection A connected tool, for what its owner approved
session Authorization: Bearer Code acting as a signed-in person; the token is renewed when it expires
none — Shares, requests and grants reached by slug or token
import { Revoked } from '@kiunke.dev/revoked';

const revoked = new Revoked({
  server: 'https://api.example.com',
  apiKey: process.env.REVOKED_API_KEY,
});

Collection writes are bound to a workspace, and the server compares the workspace field with the caller's. The SDK fills it in. For a session, it reads the active workspace from the account. For an API key, it asks GET /api/me. On a server without that endpoint, the workspace id is passed as workspace when the client is created.

Shares

const record = await revoked.vault.create({ key: 'shipping_address', label: 'Delivery address', value: 'Musterstraße 12, Berlin' });
const link = await revoked.links.create({ label: 'Delivery address', records: [record.id], maxViews: 3 });

revoked.links.url(link);      // https://api.example.com/s/<slug>
await revoked.links.revoke(link.id);

A share's slug is 24 random characters, drawn from a cryptographic random source, unless one is given. Anything shorter can be guessed.

An API key or a connected tool reaches the vault through revoked.vault, which covers only the sections it was given and lets it change only the records it wrote. revoked.records is the vault as a signed-in person sees it.

const entries = await revoked.vault.list();
const phone = await revoked.vault.find('phone');
await revoked.vault.create({ key: 'now_playing', label: 'Now playing', value: 'Track 7', section: sectionId });

section takes a section's id, which Copy ID (API) in the section's menu puts on the clipboard. Left out, the record goes into the key's first section.

Opening a share

import { createPublicClient } from '@kiunke.dev/revoked/public';

const client = createPublicClient({ server: 'https://api.example.com' });
const preview = await client.links.preview(slug);   // gates only; consumes no view
const share = await client.links.open(slug, { password });

open consumes one view and is never retried. For a share that requires a proven identity, the identity's key signs the server's challenge on this device. The returned handshakeToken skips the signature on the next read:

import { generateIdentityKey } from '@kiunke.dev/revoked/identity';

const key = await generateIdentityKey();
const identity = await revoked.identities.createFromKey(key, { name: 'Billing' });
const share = await client.links.open(slug, { identity: { id: identity.id, key } });

The private key is generated with WebCrypto and is not extractable unless extractable: true is passed. Only the public key reaches the server.

Encrypted entries are opened with the key after #k= in the share's address, which never reaches the server:

import { openSealedShare } from '@kiunke.dev/revoked/sealed';

const { opened } = await openSealedShare(client.links, 'https://api.example.com/s/<slug>#k=<key>');

Requests

const request = await revoked.requests.create({ label: 'Delivery details', template: templateId });
revoked.requests.appLink(request);          // revoked://r/… for the responder
const answers = await revoked.requests.responses(request.id);

Answering a request takes a session on the request's server (revoked.public.requests.submit). The answer becomes a grant in the responder's own workspace.

Example: collecting details and following the answer

A shop asks a customer for delivery details, is told the moment they answer, reads the current values, and hears when the customer withdraws them. The API key needs Manage requests, View requests, View identities (the request asks as the workspace's primary identity) and Manage webhooks. PUBLIC_URL is an address the Revoked server can reach. A server started with ALLOW_PRIVATE_CALLBACKS=true also delivers to localhost.

import { createServer } from 'node:http';
import { Revoked } from '@kiunke.dev/revoked';
import { verifyWebhook } from '@kiunke.dev/revoked/webhooks';

const revoked = new Revoked({ server: process.env.REVOKED_SERVER!, apiKey: process.env.REVOKED_API_KEY! });

const request = await revoked.requests.create({ label: 'Delivery details', template: process.env.TEMPLATE_ID, maxResponses: 1 });
console.log('Link for the customer:', revoked.requests.appLink(request));

const endpoint = await revoked.webhooks.endpoints.create({
  url: `${process.env.PUBLIC_URL}/hooks/revoked`,
  events: ['response.submitted', 'response.changed', 'response.revoked'],
});

createServer(async (req, res) => {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  let event;
  try {
    event = await verifyWebhook({
      body: Buffer.concat(chunks).toString('utf8'),
      signature: req.headers['revoked-signature'] as string | undefined,
      secret: endpoint.secret,
    });
  } catch {
    res.writeHead(400).end();
    return;
  }
  res.writeHead(204).end();

  switch (event.type) {
    case 'response.submitted':
    case 'response.changed': {
      const [answer] = await revoked.requests.responses(request.id);
      console.log(`${answer?.senderName} answered:`, answer?.data);
      break;
    }
    case 'response.revoked':
      console.log('The answer was withdrawn. Its values are no longer readable.');
      break;
  }
}).listen(4000);

The answer is a living grant in the customer's own workspace. When they correct the address in their vault, response.changed arrives and responses returns the new value. When they revoke it, the values stop being readable. No copy is left behind.

Webhooks

import { verifyWebhook } from '@kiunke.dev/revoked/webhooks';

const event = await verifyWebhook({
  body: rawBody,                                  // the bytes as received
  signature: request.headers.get('Revoked-Signature'),
  secret: process.env.REVOKED_WEBHOOK_SECRET,
});
switch (event.type) {
  case 'link.revoked':
    console.log(event.data.id, event.data.kind);
    break;
}

The signature, its age (300 seconds by default) and both secrets during a rotation are checked as described in Verifying the signature. Deliveries can repeat. Duplicates are recognised by event.id.

Connected tools

@kiunke.dev/revoked/connect builds revoked://p, revoked://pr and revoked://connect links, validates them as the app does, and completes the connection:

import { connectLink, createPkce, createState, exchangeCode, readAnswer } from '@kiunke.dev/revoked/connect';

const pkce = await createPkce();
const state = createState();
const link = connectLink({
  client: 'https://tool.example',
  name: 'Guestbook',
  answer: { redirect: 'https://tool.example/callback', state, challenge: pkce.challenge },
  section: {},
});
// Back at the return address:
const answer = readAnswer(location.href, state);
const { token } = await exchangeCode({ server: answer.server, code: answer.code!, verifier: pkce.verifier, redirectUri: 'https://tool.example/callback' });
const tool = new Revoked({ server: answer.server, connection: token });

pollForToken collects a polled answer instead. checkCode returns the code both sides display.

Trust chain

@kiunke.dev/revoked/trust checks the trust chain on the device rather than trusting any one server's verdict. A DNS lookup function is required. The SDK sends no domain name to a resolver it was not given.

import { verifySharer } from '@kiunke.dev/revoked/trust';
import { promises as dns } from 'node:dns';

const verdict = await verifySharer(preview.sharer, { resolveTxt: (name) => dns.resolveTxt(name) });
// verdict.state: 'verified' | 'dnsMissing' | 'unverified' | 'spoofed' | 'revoked'

Errors

Every failure is a RevokedError with the HTTP status, the server's stable code, and fields for validation errors. Subclasses support instanceof checks: ValidationError, AuthenticationError, PermissionError, NotFoundError, ConflictError, GoneError (revoked, expired or used up), PayloadTooLargeError, RateLimitedError (with retryAfter), ServerError, NetworkError and TimeoutError.

code is typed with every code the server sends. A newer server's code still passes through unchanged. Error codes lists each one with its message.

Lists, filters and retries

import { f } from '@kiunke.dev/revoked';

for await (const link of revoked.links.iterate({ filter: f`status = ${'active'} && label ~ ${userInput}` })) {
  // every page, in order
}

f escapes each interpolated value, so input cannot add a clause of its own. GET requests and calls documented as idempotent are retried after a network failure or a 502, 503 or 504. A 429 is retried only when the server asks for a wait under retry.maxWaitMs, which defaults to 10 seconds. A request that consumes something, such as a view, a nonce or a single-use download token, is never retried.

Versions

The SDK is versioned apart from the server and stays in 0.x while the API does. A newer server's fields, enum values, error codes and webhook event types reach the caller untouched. Any route can be called with revoked.request(path, options), with the client's credential, retries and error decoding.