@adukilabs/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,10 @@
 # @adukilabs/sdk
 
-The Aduki API client for programs that use an API key: servers, scripts, scheduled jobs and workers. It calls Aduki Mail's REST API and JMAP with `Authorization: Key <key>`. There is no sign-in, no browser storage and no DPoP. It is written in TypeScript and ships as ES2022 modules with declarations. It uses web platform APIs only (`fetch`, WebCrypto) and has no dependencies. It runs on Node 20+, Deno, Bun and in workers. Apache 2.0.
+The Aduki API clients for programs: servers, scripts, scheduled jobs and workers. There are two entry points:
+- `Api` calls Aduki Mail's REST API and JMAP with a Mail API key (`Authorization: Key <key>`).
+- `IdClient` reaches the workspace drive on Aduki Store and Aduki Space with an Aduki ID service-client key. It trades the key for DPoP-bound tokens ([Machine access](#machine-access-store-and-space-with-a-service-client-key)).
+
+There is no sign-in and no browser storage. It is written in TypeScript and ships as ES2022 modules with declarations. It uses web platform APIs only (`fetch`, WebCrypto) and has no dependencies. It runs on Node 20+, Deno, Bun and in workers. Apache 2.0.
 
 ```sh
 npm install @adukilabs/sdk
@@ -48,6 +52,7 @@ Every call is on `https://mail.aduki.pro` (option `root` changes it). The scope
 | `api.contacts` | `get(hex)`, `list`, `search`, `groups`, `group`, `sync` [`contacts:read`]; `delete` [`contacts:write`] |
 | `api.calendar` | `calendar(hex)`, `event(hex)`, `calendars`, `events`, `range`, `upcoming`, `search` [`calendars:read`]; `deleteEvent` [`calendars:write`] |
 | `api.keys` | the workspace's keys: `list` (all, `active`, `expired`), `get` [`tenant.keys:read`]; `rename`, `rotate` (a new secret, returned once), `delete` [`tenant.keys:write`] |
+| `api.tenant` | the workspace: `get`, `bySlug` [`tenants:read`], `security` [`security:read`], `services` [`mailservices:read`]; see [Workspace administration](#workspace-administration) |
 | `api.jmap` | JMAP (RFC 8620, 8621) on the same key: `session`, `call`, `method`, `upload`, `download`. Signing in needs `mail:read`; `EmailSubmission/set` needs `mail:send` |
 | `api.call` | any other `user` or `tenant` route under `/v1`: `api.call('GET', 'tenant/domains')` |
 
@@ -55,9 +60,116 @@ Lists take `{ page, limit }` (pages from 1) or `{ after, limit }` (a cursor), wi
 
 Making a key and changing a key's scopes are only for a signed-in owner; a key gets `403` for both. `createKey()` makes a random key with its SHA-256 hash and prefix, as the server stores them.
 
+## Workspace administration
+
+`api.tenant` covers the workspace routes of Aduki Mail (`/v1/tenant/*`). A key reaches them only with `tenant` scopes (`tenant.domains:read`, `tenant.**`, ...), which only a workspace owner can give it. The scope each call needs is in brackets.
+
+| | Calls |
+|---|---|
+| `api.tenant.domains` | `add({name, kind?, selector?, meta?})` returns the hex; `list` (all, `active`, `pending`), `get(hex)` (the record with its DNS records: `dkim`, the SPF, DMARC, MTA-STS and BIMI snapshots), `byName` [`domains:read`]; `rename`, `kind`, `selector`, `auth`, `meta`, `delete` [`domains:write`] |
+| `api.tenant.domains.dkim` | a DKIM key change with no gap: `stage` (publish `pending.value` as TXT at `pending.name`), `check` [`domains:read`], `confirm`, `cancel` [`domains:write`]; `state` [`domains:read`] |
+| `api.tenant.aliases` | extra addresses of a member's mailbox on a verified domain: `list({user?})` [`aliases:read`]; `add(user, address)`, `remove(address)` [`aliases:write`] |
+| `api.tenant.members` | `list()` [`tenants:read`]; `list({state: 'active' \| 'owners'})`, `search` [`members:read`]; `remove(user)` [`tenants:write`] |
+| `api.tenant.rules` | spam rules: `list` (all, `active`, by `target`), `get`, `byName` [`rules:read`]; `add`, `edit` (one call per field), `delete` [`rules:write`] |
+| `api.tenant.webhooks` | delivery events: `list` (all, `active`, by `event`), `get` [`webhooks:read`]; `add` (returns the secret once), `edit`, `rotate` (a new secret, returned once), `delete` [`webhooks:write`] |
+| `api.tenant.quotas` | `list`, `get(metric)` [`quotas:read`]; `add`, `edit`, `delete` [`quotas:write`] |
+| `api.tenant.audits` | `list({user?, action? \| outcome? \| ip?})` [`audits:read`]; `get(hex)` [`tenants:read`] |
+| `api.tenant.usage` | `list`, `summary`, `metric` [`usage:read`] |
+| `api.tenant.holidays` | `list({region?, year?})`, `region` [`tenant:read`]; `add` (a closure, or `{exclude: true, region, date}`), `remove`, `setRegion` (null clears it) [`tenants:write`] |
+| `api.tenant.schedule` | booking templates and resources (rooms, equipment): `templates`, `template`, `resources`, `resource` [`tenant:read`]; `addTemplate`, `editTemplate`, `setRules`, `deleteTemplate`, `addResource`, `editResource`, `deleteResource` [`tenants:write`] |
+| `api.keys` | the workspace's API keys (see above) |
+
+```js
+const hex = await api.tenant.domains.add({ name: 'acme.example' }); // domains:write
+const domain = await api.tenant.domains.get(hex);                   // domains:read
+const staged = await api.tenant.domains.dkim.stage(hex);            // domains:write
+// publish staged.pending.value as a TXT record at staged.pending.name, then:
+if ((await api.tenant.domains.dkim.check(hex)).ready) await api.tenant.domains.dkim.confirm(hex);
+```
+
+What a key cannot do:
+- Invite people, change roles or grants, add or remove service clients, or change the workspace's policy. Those are Aduki ID's, and Aduki ID's own routes take no key and no service-client token: they need a signed-in person.
+- Make a key or change a key's scopes (`403`).
+- Reach Store or Space: they take only DPoP-bound Aduki ID tokens. Use `IdClient` with a service-client key (below).
+
+## Machine access: Store and Space with a service-client key
+
+`IdClient` is the second entry point. It is for a workspace's programs on Aduki Store (the workspace drive) and Aduki Space. It takes an Aduki ID **service-client key**, `adk_<client hex>_<secret>`. That is a different key from a Mail API key (`adk_<64 hex>`): a workspace owner makes the service client and its key in Aduki ID and grants the client its permissions. `Api` and `IdClient` are separate because their keys, services and rules differ. A program that needs both makes both.
+
+```js
+import { IdClient } from '@adukilabs/sdk';
+
+const id = new IdClient({ key: process.env.ADUKI_CLIENT_KEY });
+
+const quota = await id.store.quota();                        // store.read
+const root = await id.store.list();                          // the workspace drive root
+const up = await id.store.upload(bytes, { name: 'report.pdf', folder: root.folders[0]?.id });  // store.write
+const tasks = await id.space.tasks({ status: 'open' });      // space.use + tasks.read
+await id.space.createTask({ title: 'Nightly import' });      // tasks.write
+```
+
+How it works:
+- The key never goes to Store or Space. `IdClient` trades it at Aduki ID (`POST https://id.aduki.pro/v1/tokens {key, audience}`) for a 10-minute token per audience (`store`, `space`).
+- Every exchange carries a DPoP proof, so the token is bound to a key pair the program holds (`cnf.jkt`). Store and Space accept only bound tokens. A token that comes back unbound (an Aduki ID without machine access) is a `ProtocolError`.
+- The key pair is a non-extractable ES256 (P-256) WebCrypto key, made in memory on first use. It needs no IndexedDB and no browser API, so it runs on Node 20+, Deno, Bun and in workers.
+  - Option `storage` keeps the key pair in any async store that holds a `CryptoKeyPair` as is (key `dpop.key`).
+  - Option `dpop` takes a `Dpop` you made yourself.
+  - A new key pair costs nothing: a restarted program simply gets new tokens.
+- Tokens are cached per audience and renewed before they end: `renew` seconds before (default 60), at most half their lifetime. Callers that ask at the same time share one exchange.
+- If Aduki ID asks for a nonce (`401 auth.nonce`), the exchange is sent once more with it.
+- A `401` from Store or Space renews the token once and sends the request again.
+- Options: `base` (Aduki ID's origin, exactly its issuer), `fetch`, `clock`, `store: {root, files}`, `space: {root}`. `id.token(audience)` and `id.fetch(audience, url, init)` reach any other audience the client may hold.
+
+What Aduki ID requires:
+- A `store` token needs `store.read` or `store.write` in the client's grants.
+- A `space` token needs `space.use`, Space switched on, and the workspace in good standing.
+- Otherwise the exchange is refused: `403 access.denied`, or `403 app.disabled` when the app is off. A bad, revoked or expired key is `UnauthorizedError` (`auth.invalid`).
+- Strict permissions never reach a service client.
+
+### `id.store`: the workspace drive
+
+A program reaches the workspace drive only, outside the Space folder. It never has a drive of its own and never reaches a member's or a personal drive (`404`). What it may do depends on its permissions: `store.read` reads, and `store.write` also creates, renames, moves, trashes, restores and uploads. `store.share` and `store.admin` give it nothing more.
+
+| | Calls |
+|---|---|
+| quota | `quota()` (`GET /v1/quota`) |
+| folders and files | `list({parent?, trashed?})`, `folder(id)`, `file(id)`; `createFolder(name, {parent?})`, `createFile(name, {folder?, mime?})`, `updateFolder`, `updateFile` (rename, move, trash, restore), `trashFolder`, `trashFile`, `restoreFolder`, `restoreFile` |
+| uploads | `upload(content, {name, folder?} \| {file})`. Hashes the content as Store does (FastCDC 2020 cut points, BLAKE3), begins a version, sends only the chunks the server lacks to `files.aduki.pro` and commits. Run it again with the same `key` to resume. Options: `progress`, `attrs`, `signal`, a precomputed `manifest`. Each step is also a call of its own: `begin`, `putChunk`, `commit`, `abort` |
+| versions | `versions(file)`, `version(id)` (the chunks still missing) |
+| downloads | `content(file, {version?, range?, etag?})` (a Response: `206` for a range, `304` for an unchanged `etag`), `download` (a Blob) |
+| renditions | `media(version)` (thumbnails, posters, previews), `derivative(id, {range?})` |
+| other routes | `call(method, path, {query?, body?})` |
+
+What Store refuses to programs (`ClientRefusedError`, `403 access.denied` with reason `client`), so `id.store` has no call for it: shares and public links, devices, reports, search, read tickets, and the change feed.
+
+### `id.space`: Space routes that are neither strict nor money
+
+A program may call every Space route that is neither strict nor a money route, within the bits its grant gives (`space.use` plus the route's bit, for example `tasks.write` or `tickets.write`). It sees the rows a person with those bits and no team would see.
+
+| | Calls |
+|---|---|
+| any route | `call(method, path, {query, body, key, version})` returns `{data, status, etag}`; `list(path, query, {limit, after})`; `all(path, query)` goes through every page |
+| tasks | `tasks(filters)`, `task(id)`, `createTask` (a new `Idempotency-Key` each time unless you pass `key`), `updateTask(id, changes, {version})` (`If-Match`) |
+| check-ins | `checkins(task)`, `checkin(task, {body, minutes, proof?})` |
+| tickets | `tickets(filters)`, `ticket(id)`, `createTicket`, `updateTicket`, `messages(ticket)`, `reply(ticket, body, {internal?})` |
+| the workspace | `teams()`, `directory()`, `activity(filters)` (what a program did has `kind: "client"`), `search(q, {entity?, limit?})`, `settings()` (read only) |
+
+What Space refuses to programs (`ClientRefusedError`): every strict route and every money route. These are refunds, charges, payouts, rails and gateways, staff management and payroll, node management, settings changes, hooks, endpoints and exports. A program has no shifts, payslips or leave of its own.
+
+### Errors of `IdClient`
+
+| Answer | Error | What it means |
+|---|---|---|
+| `401` at Aduki ID | `UnauthorizedError` (`auth.invalid`) | the key is unknown, revoked, expired or used outside its networks |
+| `401 auth.dpop`, `auth.nonce` | `ProofError` | the proof was refused (a clock or key problem) |
+| `403 access.denied`, reason `client` | `ClientRefusedError` | the route is for people only; another token does not help |
+| `403 access.denied` | `NetworkError` | the client's grants lack the permission |
+| `403 app.disabled` | `NetworkError` | the app is off, or the workspace is not in good standing (Space: read-only) |
+| `429` | `RateLimitedError` | `retryAfter` holds the seconds to wait |
+
 ## Errors
 
-A refused call throws a typed error:
+A refused call of `Api` throws a typed error:
 
 | Answer | Error | What it means |
 |---|---|---|

package/dist/api/api.d.ts

@@ -1,4 +1,5 @@
 import { Jmap } from '../jmap.js';
+import { Tenant } from './tenant.js';
 import type * as model from './model.js';
 import type { Page, PageQuery } from './model.js';
 /** The mail host (REST under `/v1`, JMAP at the root). */
@@ -39,6 +40,8 @@ export declare class Api {
     readonly contacts: ContactsApi;
     readonly calendar: CalendarApi;
     readonly keys: Keys;
+    /** the workspace: domains, aliases, members, rules, webhooks, quotas, audits, usage, holidays, scheduling (`tenant.*` scopes) */
+    readonly tenant: Tenant;
     readonly random: () => string;
     constructor(options: ApiOptions);
     /**

package/dist/api/api.js

@@ -4,14 +4,15 @@
 // (narrowed to what the workspace owner who made it may do) are its rights.
 //
 // Aduki Mail (`mail.aduki.pro`) is the one service that accepts API keys:
-// its REST API under `/v1` (the `user` and `tenant` routes; never
-// `platform`) and its JMAP endpoints. Aduki ID, Store and Space take only
-// Aduki ID tokens.
+// its REST API under `/v1` (the `user` and `tenant` routes, see `tenant.ts`;
+// never `platform`) and its JMAP endpoints. Aduki ID, Store and Space take
+// only Aduki ID tokens (guide/api-keys.md).
 import { rejection } from '../envelope.js';
 import { ProtocolError } from '../errors.js';
 import { json, send, url } from '../http.js';
 import { Jmap } from '../jmap.js';
 import { createKey } from './key.js';
+import { Tenant } from './tenant.js';
 /** The mail host (REST under `/v1`, JMAP at the root). */
 export const ROOT = 'https://mail.aduki.pro';
 export class Api {
@@ -23,6 +24,8 @@ export class Api {
     contacts;
     calendar;
     keys;
+    /** the workspace: domains, aliases, members, rules, webhooks, quotas, audits, usage, holidays, scheduling (`tenant.*` scopes) */
+    tenant;
     #key;
     #root;
     #fetch;
@@ -46,6 +49,7 @@ export class Api {
         this.contacts = new ContactsApi(this);
         this.calendar = new CalendarApi(this);
         this.keys = new Keys(this);
+        this.tenant = new Tenant(this);
     }
     /** The request with the key added (an absolute URL, or a path on the mail host). */
     #send(input, init) {

package/dist/api/id.d.ts

@@ -0,0 +1,75 @@
+import type { TokenSource } from '../client.js';
+import { Dpop } from '../dpop.js';
+import type { KeyStore } from '../dpop.js';
+import { SpaceApi } from './space.js';
+import type { SpaceApiOptions } from './space.js';
+import { StoreApi } from './store.js';
+import type { StoreApiOptions } from './store.js';
+/** Aduki ID (the token issuer). */
+export declare const ID = "https://id.aduki.pro";
+export interface IdClientOptions {
+    /** the service-client key, `adk_<client hex>_<secret>` (made by a workspace owner in Aduki ID; shown once) */
+    key: string;
+    /**
+     * Aduki ID's origin, exactly its issuer (default `https://id.aduki.pro`):
+     * the proof of the exchange is signed for `<base>/v1/tokens`
+     */
+    base?: string | undefined;
+    /** the transport for every call, Aduki ID, Store and Space (default global fetch) */
+    fetch?: typeof fetch | undefined;
+    /** the DPoP key the tokens are bound to (default: generated, see `storage`) */
+    dpop?: Dpop | undefined;
+    /**
+     * Where a generated key is kept (key `dpop.key`): any async store that
+     * holds a CryptoKeyPair as is. Default: memory, a new key per IdClient.
+     * Ignored with `dpop`.
+     */
+    storage?: KeyStore | undefined;
+    /** renew a token this many seconds before it ends (default 60; at most half its lifetime) */
+    renew?: number | undefined;
+    /** the clock in milliseconds (default `Date.now`; tests pass a fake) */
+    clock?: (() => number) | undefined;
+    /** Store's roots and timer (`api.store`) */
+    store?: StoreApiOptions | undefined;
+    /** Space's root (`api.space`) */
+    space?: SpaceApiOptions | undefined;
+}
+/**
+ * A workspace's program on Store and Space. `store` is the workspace drive,
+ * `space` the non-strict, non-money routes of Aduki Space; `token` and
+ * `fetch` reach any other audience the client may hold.
+ */
+export declare class IdClient implements TokenSource {
+    #private;
+    /** the workspace drive on Aduki Store (`store.read`, `store.write`) */
+    readonly store: StoreApi;
+    /** Aduki Space's routes that are neither strict nor money (`space.use` and the route's bit) */
+    readonly space: SpaceApi;
+    /** Aduki ID's origin */
+    readonly base: string;
+    constructor(options: IdClientOptions);
+    /** The DPoP key the tokens are bound to (made on first use). */
+    key(): Promise<Dpop>;
+    /**
+     * A valid token for `audience` (`store`, `space`, ...): the cached one, or
+     * a new one from Aduki ID when there is none or it ends within `renew`
+     * seconds. Concurrent callers share one exchange. A refused exchange
+     * throws the typed error (`UnauthorizedError` for a bad, revoked or expired
+     * key; `NetworkError 403 access.denied` when the client's grants hold no
+     * right to the audience; `403 app.disabled` when the app is off).
+     */
+    token(audience: string): Promise<string>;
+    /** Renews the token of `audience` unless it was already replaced since `stale` (`TokenSource`). */
+    rotate(audience: string, stale: string | null): Promise<{
+        token: string;
+    }>;
+    /** Drops the cached token of `audience`, or every token. */
+    forget(audience?: string): void;
+    /**
+     * Sends a request to a service of `audience` with its token
+     * (`Authorization: DPoP`) and a proof; a 401 renews the token once and
+     * sends again. Returns the raw response; a transport failure is a
+     * NetworkError. The body must be re-sendable (not a stream).
+     */
+    fetch(audience: string, input: Request | string | URL, init?: RequestInit): Promise<Response>;
+}

package/dist/api/id.js

@@ -0,0 +1,184 @@
+// Machine access: a program of a workspace on Aduki Store and Aduki Space
+// with an Aduki ID service-client key (`adk_<client hex>_<secret>`).
+//
+// The key never goes to Store or Space. `IdClient` trades it at Aduki ID
+// (`POST /v1/tokens {key, audience}`) for a ten-minute token per audience,
+// always with a DPoP proof, so the token is bound to a key pair the program
+// holds (`cnf.jkt`): Store and Space accept bound tokens only. The key pair is
+// a non-extractable ES256 (P-256) WebCrypto key, generated in memory by
+// default (no IndexedDB, no browser API: Node 20+, Deno, Bun, workers), or
+// loaded from a `KeyStore` the caller passes, or a `Dpop` the caller made.
+//
+// Tokens are cached per audience and renewed before they end; a `DPoP-Nonce`
+// challenge (`401 auth.nonce`) is answered once; a 401 from Store or Space
+// renews the token once (the core `createClient`). Every refusal is the typed
+// error of the core `refusal`: `ClientRefusedError` for a route that is not
+// for programs (`403 access.denied`, reason `client`).
+import { claims } from '../base64.js';
+import { createClient } from '../client.js';
+import { Dpop } from '../dpop.js';
+import { failure, parse, rejection } from '../envelope.js';
+import { ProtocolError } from '../errors.js';
+import { send } from '../http.js';
+import { SpaceApi } from './space.js';
+import { StoreApi } from './store.js';
+/** Aduki ID (the token issuer). */
+export const ID = 'https://id.aduki.pro';
+const SHAPE = /^adk_[0-9a-f]+_\S+$/;
+/**
+ * A workspace's program on Store and Space. `store` is the workspace drive,
+ * `space` the non-strict, non-money routes of Aduki Space; `token` and
+ * `fetch` reach any other audience the client may hold.
+ */
+export class IdClient {
+    /** the workspace drive on Aduki Store (`store.read`, `store.write`) */
+    store;
+    /** Aduki Space's routes that are neither strict nor money (`space.use` and the route's bit) */
+    space;
+    /** Aduki ID's origin */
+    base;
+    #key;
+    #transport;
+    #clock;
+    #renew;
+    #storage;
+    #dpop;
+    #client;
+    #nonce = null;
+    #held = new Map();
+    #pending = new Map();
+    constructor(options) {
+        const key = options?.key?.trim();
+        if (!key)
+            throw new TypeError('IdClient needs a key');
+        if (!SHAPE.test(key)) {
+            throw new TypeError(/^adk_[0-9a-f]{64}$/.test(key)
+                ? 'This is an Aduki Mail API key: use Api for Mail; IdClient takes an Aduki ID service-client key (adk_<hex>_<secret>)'
+                : 'An Aduki ID service-client key is adk_<hex>_<secret>');
+        }
+        this.#key = key;
+        this.base = (options.base ?? ID).replace(/\/+$/, '');
+        this.#transport = options.fetch ?? ((...args) => globalThis.fetch(...args));
+        this.#clock = options.clock ?? Date.now;
+        const renew = options.renew ?? 60;
+        if (!(Number.isFinite(renew) && renew >= 0))
+            throw new TypeError('renew is a number of seconds, not negative');
+        this.#renew = renew * 1000;
+        this.#storage = options.storage;
+        if (options.dpop)
+            this.#dpop = Promise.resolve(options.dpop);
+        this.store = new StoreApi(this, options.store);
+        this.space = new SpaceApi(this, options.space);
+    }
+    /** The DPoP key the tokens are bound to (made on first use). */
+    key() {
+        this.#dpop ??= (this.#storage ? Dpop.load(this.#storage, { clock: this.#clock }) : Dpop.generate({ clock: this.#clock })).catch((error) => {
+            this.#dpop = undefined;
+            throw error;
+        });
+        return this.#dpop;
+    }
+    /**
+     * A valid token for `audience` (`store`, `space`, ...): the cached one, or
+     * a new one from Aduki ID when there is none or it ends within `renew`
+     * seconds. Concurrent callers share one exchange. A refused exchange
+     * throws the typed error (`UnauthorizedError` for a bad, revoked or expired
+     * key; `NetworkError 403 access.denied` when the client's grants hold no
+     * right to the audience; `403 app.disabled` when the app is off).
+     */
+    async token(audience) {
+        const held = this.#held.get(audience);
+        if (held && this.#clock() < held.renew)
+            return held.token;
+        return (await this.#fresh(audience)).token;
+    }
+    /** Renews the token of `audience` unless it was already replaced since `stale` (`TokenSource`). */
+    async rotate(audience, stale) {
+        const held = this.#held.get(audience);
+        if (held && held.token !== stale && this.#clock() < held.expires)
+            return { token: held.token };
+        if (held && held.token === stale)
+            this.#held.delete(audience);
+        return { token: (await this.#fresh(audience)).token };
+    }
+    /** Drops the cached token of `audience`, or every token. */
+    forget(audience) {
+        if (audience === undefined)
+            this.#held.clear();
+        else
+            this.#held.delete(audience);
+    }
+    /**
+     * Sends a request to a service of `audience` with its token
+     * (`Authorization: DPoP`) and a proof; a 401 renews the token once and
+     * sends again. Returns the raw response; a transport failure is a
+     * NetworkError. The body must be re-sendable (not a stream).
+     */
+    async fetch(audience, input, init) {
+        if (!this.#client) {
+            const dpop = await this.key();
+            const transport = this.#transport;
+            this.#client ??= createClient({ tokens: this, fetch: (i, n) => send(transport, i, n), dpop });
+        }
+        return this.#client.fetch(audience, input, init);
+    }
+    #fresh(audience) {
+        let pending = this.#pending.get(audience);
+        if (!pending) {
+            pending = this.#exchange(audience).then((held) => {
+                this.#held.set(audience, held);
+                this.#pending.delete(audience);
+                return held;
+            }, (error) => {
+                this.#pending.delete(audience);
+                throw error;
+            });
+            this.#pending.set(audience, pending);
+        }
+        return pending;
+    }
+    /** `POST /v1/tokens {key, audience}` with a proof; once more with the server nonce on `401 auth.nonce`. */
+    async #exchange(audience) {
+        if (!audience || audience === 'id')
+            throw new TypeError('An audience other than id is needed (store, space, ...)');
+        const dpop = await this.key();
+        const target = `${this.base}/v1/tokens`;
+        const what = `POST /v1/tokens (${audience})`;
+        const body = JSON.stringify({ key: this.#key, audience });
+        let nonce = this.#nonce;
+        for (let attempt = 0;; attempt++) {
+            const headers = {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                DPoP: await dpop.proof({ method: 'POST', url: target, nonce }),
+            };
+            const response = await send(this.#transport, target, { method: 'POST', headers, body });
+            const fresh = response.headers.get('DPoP-Nonce');
+            if (fresh)
+                this.#nonce = fresh;
+            const text = await response.text();
+            if (!response.ok) {
+                const refused = failure(text);
+                const offered = fresh ?? refused?.details?.nonce;
+                if (attempt === 0 && response.status === 401 && refused?.kind === 'auth.nonce' && typeof offered === 'string' && offered) {
+                    nonce = offered;
+                    continue;
+                }
+                throw rejection(response, text, what);
+            }
+            const data = parse(text)?.data;
+            const access = data?.access;
+            if (typeof access !== 'string' || !access)
+                throw new ProtocolError(`${what}: the answer has no token`);
+            if (!dpop.bound(access)) {
+                throw new ProtocolError(`${what}: the token is not bound to the DPoP key (an Aduki ID without machine access)`);
+            }
+            const now = this.#clock();
+            const exp = Number(claims(access).exp);
+            const lifetime = Number(data.expires);
+            const expires = Number.isFinite(exp) && exp > 0 ? exp * 1000 : now + (Number.isFinite(lifetime) && lifetime > 0 ? lifetime : 600) * 1000;
+            const margin = Math.min(this.#renew, Math.max(0, (expires - now) / 2));
+            return { token: access, expires, renew: expires - margin };
+        }
+    }
+}

package/dist/api/index.d.ts

@@ -1,9 +1,22 @@
 export { Api, CalendarApi, ContactsApi, Keys, MailApi, Mailboxes, ROOT, User } from './api.js';
 export type { ApiOptions, CallOptions, Folder, Query } from './api.js';
+export { Tenant, TenantAliases, TenantAudits, TenantDkim, TenantDomains, TenantHolidays, TenantMembers, TenantQuotas, TenantRules, TenantSchedule, TenantUsage, TenantWebhooks, } from './tenant.js';
+export { ID, IdClient } from './id.js';
+export type { IdClientOptions } from './id.js';
+export { FILES, STORE, StoreApi } from './store.js';
+export type { AudienceFetch, FileChange, FolderChange, StoreApiOptions, StoreDownload, StoreUploaded, StoreUploadOptions, UploadProgress, VersionAttrs } from './store.js';
+export { SPACE, SpaceApi } from './space.js';
+export type { SpaceActivityFilters, SpaceApiOptions, SpaceCall, SpacePage, SpaceQuery, SpaceTaskFilters, SpaceTaskInput, SpaceTicketFilters, SpaceTicketInput } from './space.js';
+export { Dpop } from '../dpop.js';
+export type { KeyStore, Locks, PublicJwk } from '../dpop.js';
+export { manifest } from '../store/chunks.js';
+export type { Chunk, Content, Manifest } from '../store/chunks.js';
+export type { Begun, Derivative, FileEntry, Folder as StoreFolder, Listing, Quota as StoreQuota, Version, VersionStatus } from '../store/model.js';
+export type { Activity, Checkin, Found, Member, Message, Page as SpaceList, Reply, Settings, SupportTicket, Task, Team } from '../space/model.js';
 export { createKey, hashKey } from './key.js';
 export type { NewKey } from './key.js';
 export type * from './model.js';
-export { AdukiError, LimitError, NetworkError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
+export { AdukiError, ClientRefusedError, LimitError, NetworkError, ProofError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
 export type { NetworkErrorOptions, Refused } from '../errors.js';
 export { kinds } from '../envelope.js';
 export { CORE, Jmap, JmapError, MAIL, SUBMISSION, USING } from '../jmap.js';

package/dist/api/index.js

@@ -1,9 +1,19 @@
-// sdk/api (published on npm as `@adukilabs/sdk`): the client for programs
-// that use an Aduki API key (`Authorization: Key <key>`) on Aduki Mail's
-// REST API and JMAP. Only the core it needs (errors, envelope, http, jmap)
-// comes with it: no sign-in, session, browser storage or DPoP.
+// sdk/api (published on npm as `@adukilabs/sdk`): the clients for programs.
+// - `Api`: an Aduki Mail API key (`Authorization: Key <key>`) on Aduki Mail's
+//   REST API and JMAP.
+// - `IdClient`: an Aduki ID service-client key, traded for DPoP-bound tokens,
+//   on the workspace drive of Aduki Store and on Aduki Space (machine access).
+// Only the core they need comes with them (errors, envelope, http, jmap,
+// base64, the DPoP key and the authenticated fetch, Store's chunker): no
+// sign-in, session or browser storage.
 export { Api, CalendarApi, ContactsApi, Keys, MailApi, Mailboxes, ROOT, User } from './api.js';
+export { Tenant, TenantAliases, TenantAudits, TenantDkim, TenantDomains, TenantHolidays, TenantMembers, TenantQuotas, TenantRules, TenantSchedule, TenantUsage, TenantWebhooks, } from './tenant.js';
+export { ID, IdClient } from './id.js';
+export { FILES, STORE, StoreApi } from './store.js';
+export { SPACE, SpaceApi } from './space.js';
+export { Dpop } from '../dpop.js';
+export { manifest } from '../store/chunks.js';
 export { createKey, hashKey } from './key.js';
-export { AdukiError, LimitError, NetworkError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
+export { AdukiError, ClientRefusedError, LimitError, NetworkError, ProofError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
 export { kinds } from '../envelope.js';
 export { CORE, Jmap, JmapError, MAIL, SUBMISSION, USING } from '../jmap.js';