@adukilabs/sdk 0.0.0-stage → 0.1.2

package/dist/api/api.js

@@ -0,0 +1,365 @@
+// The API-key client: programs (servers, scripts, workers) that call Aduki
+// Mail with a tenant API key, `Authorization: Key <key>`. No sign-in, no
+// browser storage, no DPoP: the key is the credential, its stored scopes
+// (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, 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 {
+    /** the JMAP client on the same key (mail: `u.mail:read`, sending: `u.mail:send`) */
+    jmap;
+    user;
+    mail;
+    mailboxes;
+    contacts;
+    calendar;
+    keys;
+    /** the workspace: domains, aliases, members, rules, webhooks, quotas, audits, usage, holidays, scheduling (`tenant.*` scopes) */
+    tenant;
+    #key;
+    #root;
+    #fetch;
+    random;
+    constructor(options) {
+        const key = options?.key?.trim();
+        if (!key)
+            throw new TypeError('Api needs a key');
+        if (/\s/.test(key))
+            throw new TypeError('An API key has no whitespace');
+        this.#key = key;
+        this.#root = (options.root ?? ROOT).replace(/\/+$/, '');
+        const transport = options.fetch ?? ((...args) => globalThis.fetch(...args));
+        this.#fetch = (input, init) => send(transport, input, init);
+        this.random = options.random ?? (() => crypto.randomUUID());
+        const keyed = { fetch: (_audience, input, init) => this.#send(input, init) };
+        this.jmap = new Jmap({ session: keyed, root: this.#root });
+        this.user = new User(this);
+        this.mail = new MailApi(this);
+        this.mailboxes = new Mailboxes(this);
+        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) {
+        const target = typeof input === 'string' && !/^https?:\/\//.test(input) ? url(this.#root, input.replace(/^\/+/, '')) : input;
+        const request = new Request(target, init);
+        request.headers.set('Authorization', `Key ${this.#key}`);
+        return this.#fetch(request);
+    }
+    /**
+     * Sends a request to the mail host with the key (`path` relative to the
+     * host, as `v1/user`, or an absolute URL) and returns the raw response.
+     * A transport failure is a NetworkError; the answer is not checked.
+     */
+    fetch(path, init) {
+        return this.#send(path, init);
+    }
+    /**
+     * Any REST route under `/v1` (`path` without it, as `user/profile`):
+     * returns the envelope's `data` (null for `204`); a refusal throws the
+     * typed error of `errors.refusal` (UnauthorizedError for a bad key,
+     * NetworkError with `403 access.denied` for a scope the key lacks,
+     * RateLimitedError with `retryAfter`, ...).
+     */
+    async call(method, path, options = {}) {
+        let target = `v1/${path.replace(/^\/+/, '')}`;
+        const query = new URLSearchParams();
+        for (const [name, value] of Object.entries(options.query ?? {}))
+            if (value !== undefined)
+                query.set(name, String(value));
+        if ([...query].length)
+            target += `?${query}`;
+        const headers = { Accept: 'application/json' };
+        let body;
+        if (options.body !== undefined) {
+            const request = json(options.body);
+            Object.assign(headers, request.headers);
+            body = request.body;
+        }
+        if (options.idempotency)
+            headers['Idempotency-Key'] = options.idempotency;
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = body;
+        if (options.signal)
+            init.signal = options.signal;
+        const response = await this.#send(target, init);
+        const text = await response.text();
+        const what = `${method} /${target.split('?')[0]}`;
+        if (!response.ok)
+            throw rejection(response, text, what);
+        if (response.status === 204 || !text.trim())
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new ProtocolError(`${what} answer is not JSON`);
+        }
+        return (parsed && typeof parsed === 'object' && 'success' in parsed ? (parsed.data ?? null) : parsed);
+    }
+    /** `GET` of a list route with paging (see PageQuery). */
+    page(path, query = {}) {
+        return this.call('GET', path, { query: query });
+    }
+    /** Every item of a list route, following the cursor (`after`) page by page. */
+    async *all(path, query = {}) {
+        let after;
+        do {
+            const page = await this.page(path, { ...query, after });
+            yield* page.items ?? [];
+            after = page.next || undefined;
+        } while (after);
+    }
+}
+const seg = (value) => encodeURIComponent(value);
+/** The account the key acts as. Scope `users:read`. */
+export class User {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user`: the account. */
+    get() {
+        return this.#api.call('GET', 'user');
+    }
+    /** `GET /v1/user/profile`: name, address, workspace, role, plan, storage. */
+    profile() {
+        return this.#api.call('GET', 'user/profile');
+    }
+    /** `GET /v1/user/keys`: the API keys made by this account (never the keys themselves). */
+    keys(query = {}) {
+        return this.#api.page('user/keys', query);
+    }
+    /** `GET /v1/user/aliases` (scope `aliases:read`). */
+    aliases() {
+        return this.#api.call('GET', 'user/aliases');
+    }
+}
+/** Mail over REST. Reading needs `mail:read`, changes `mail:write`, sending `mail:send`. */
+export class MailApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /**
+     * `POST /v1/user/mail/send`: a plain-text message, a copy filed in Sent;
+     * returns its hex. `from` defaults to the default identity (an address the
+     * account may not send as is `403`). Sent with an `Idempotency-Key`
+     * (`idempotency`, else a random one): a retry with the same key never
+     * sends twice. A full queue is `RateLimitedError` (`mail.queue_busy`).
+     */
+    async send(input, options = {}) {
+        const body = { to: input.to, subject: input.subject, text: input.text };
+        if (input.cc?.length)
+            body.cc = input.cc;
+        if (input.from)
+            body.from = input.from;
+        const data = await this.#api.call('POST', 'user/mail/send', { body, idempotency: options.idempotency ?? this.#api.random() });
+        if (typeof data?.hex !== 'string')
+            throw new ProtocolError('Send answer has no hex');
+        return data.hex;
+    }
+    /** `GET /v1/user/mail/<folder>`: the messages of a folder, newest first. */
+    list(folder, query = {}) {
+        return this.#api.page(`user/mail/${folder}`, query);
+    }
+    /** `GET /v1/user/mail/inbox/unread`. */
+    /** `GET /v1/user/mail/{hex}`: one message (scope `mail:read`); a deleted or unknown one is a 404. */
+    get(hex) {
+        return this.#api.call('GET', `user/mail/${seg(hex)}`);
+    }
+    unread(query = {}) {
+        return this.#api.page('user/mail/inbox/unread', query);
+    }
+    /** `GET /v1/user/mail/folder/{name}`: a mailbox by name. */
+    folder(name, query = {}) {
+        return this.#api.page(`user/mail/folder/${seg(name)}`, query);
+    }
+    /** `GET /v1/user/mail/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/mail/search/${seg(text)}`, query);
+    }
+    /** `GET /v1/user/mail/threads`. */
+    threads(query = {}) {
+        return this.#api.page('user/mail/threads', query);
+    }
+    /** `GET /v1/user/mail/thread/{thread}`: the messages of a thread. */
+    thread(thread, query = {}) {
+        return this.#api.page(`user/mail/thread/${seg(thread)}`, query);
+    }
+    /**
+     * `GET /v1/user/mail/changes`: what changed in a mailbox since `since` (a
+     * modseq, 0 for everything). Pass the `uidvalidity` last seen: a stale one
+     * comes back with `reset`.
+     */
+    changes(input) {
+        return this.#api.call('GET', 'user/mail/changes', {
+            query: { mailbox: input.mailbox, since: input.since ?? 0, uidvalidity: input.uidvalidity, limit: input.limit },
+        });
+    }
+    /** `PATCH /v1/user/mail/{hex}/flags`: adds and removes flags (`\\Seen`, `\\Flagged`, ...). */
+    async flags(hex, change) {
+        await this.#api.call('PATCH', `user/mail/${seg(hex)}/flags`, { body: { add: change.add ?? [], remove: change.remove ?? [] } });
+    }
+    /** `PATCH /v1/user/mail/{hex}/mailbox`: moves a message to another mailbox (hex). */
+    move(hex, mailbox) {
+        return this.#api.call('PATCH', `user/mail/${seg(hex)}/mailbox`, { body: { mailbox } });
+    }
+    /** `DELETE /v1/user/mail/{hex}`. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `user/mail/${seg(hex)}`);
+    }
+}
+/** Mailboxes over REST: `mailbox:read`. */
+export class Mailboxes {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/mailbox`. */
+    list(query = {}) {
+        return this.#api.page('user/mailbox', query);
+    }
+    /** `GET /v1/user/mailbox/unread`: the mailboxes with unread mail. */
+    unread(query = {}) {
+        return this.#api.page('user/mailbox/unread', query);
+    }
+    /** `GET /v1/user/mailbox/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/mailbox/search/${seg(text)}`, query);
+    }
+}
+/** The address book over REST: `contacts:read`, `contacts:write` to delete. */
+export class ContactsApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/contacts`. */
+    list(query = {}) {
+        return this.#api.page('user/contacts', query);
+    }
+    /** `GET /v1/user/contacts/{hex}`: one contact (scope `contacts:read`). */
+    get(hex) {
+        return this.#api.call('GET', `user/contacts/${seg(hex)}`);
+    }
+    /** `GET /v1/user/contacts/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/contacts/search/${seg(text)}`, query);
+    }
+    /** `GET /v1/user/contacts/groups`. */
+    groups(query = {}) {
+        return this.#api.page('user/contacts/groups', query);
+    }
+    /** `GET /v1/user/contacts/group/{group}`: the cards of a group. */
+    group(group, query = {}) {
+        return this.#api.page(`user/contacts/group/${seg(group)}`, query);
+    }
+    /**
+     * `GET /v1/user/contacts/sync`: one page of changes since `since` (the
+     * `token` of the last answer; none for the whole book). A token the server
+     * no longer knows throws SyncResetError: sync again without one.
+     */
+    sync(input = {}) {
+        return this.#api.call('GET', 'user/contacts/sync', { query: { since: input.since, limit: input.limit } });
+    }
+    /** `DELETE /v1/user/contacts/{hex}`. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `user/contacts/${seg(hex)}`);
+    }
+}
+/** Calendars and events over REST: `calendars:read`, `calendars:write` to delete. */
+export class CalendarApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/calendars`. */
+    /** `GET /v1/user/calendars/{hex}`: one calendar (scope `calendars:read`). */
+    calendar(hex) {
+        return this.#api.call('GET', `user/calendars/${seg(hex)}`);
+    }
+    /** `GET /v1/user/events/{hex}`: one event with its `calendar` hex (scope `calendars:read`). */
+    event(hex) {
+        return this.#api.call('GET', `user/events/${seg(hex)}`);
+    }
+    calendars(query = {}) {
+        return this.#api.page('user/calendars', query);
+    }
+    /** `GET /v1/user/events`. */
+    events(query = {}) {
+        return this.#api.page('user/events', query);
+    }
+    /** `GET /v1/user/events/range/{from}/{to}`: occurrences between two instants (RFC 3339, or Dates). */
+    range(from, to, query = {}) {
+        const iso = (t) => (t instanceof Date ? t.toISOString() : t);
+        return this.#api.page(`user/events/range/${seg(iso(from))}/${seg(iso(to))}`, query);
+    }
+    /** `GET /v1/user/events/upcoming`. */
+    upcoming(query = {}) {
+        return this.#api.page('user/events/upcoming', query);
+    }
+    /** `GET /v1/user/events/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/events/search/${seg(text)}`, query);
+    }
+    /** `DELETE /v1/user/events/{hex}`. */
+    async deleteEvent(hex) {
+        await this.#api.call('DELETE', `user/events/${seg(hex)}`);
+    }
+}
+/**
+ * The workspace's API keys: `tenant.keys:read`, `tenant.keys:write` to
+ * rename, rotate and revoke. Making a key or changing its scopes is for a
+ * workspace owner signed in (a key is never an owner: `403`).
+ */
+export class Keys {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/tenant/keys`, `.../active` or `.../expired`. */
+    list(query = {}) {
+        const { state, ...rest } = query;
+        return this.#api.page(state ? `tenant/keys/${state}` : 'tenant/keys', rest);
+    }
+    /** `GET /v1/tenant/keys/{hex}`: name, prefix, scopes, dates (never the hash). */
+    get(hex) {
+        return this.#api.call('GET', `tenant/keys/${seg(hex)}`);
+    }
+    /** `PATCH /v1/tenant/keys/{hex}/name`. */
+    async rename(hex, name) {
+        await this.#api.call('PATCH', `tenant/keys/${seg(hex)}/name`, { body: { name } });
+    }
+    /**
+     * A new secret for key `hex` (`PATCH /v1/tenant/keys/{hex}/hash`): makes a
+     * random key, stores its hash and returns it. The old secret stops working
+     * at once (also for this client, if it is the key in use: make a new Api
+     * with the returned key); the key keeps its hex, name and scopes, and its
+     * prefix becomes the new key's (servers before ADK-MAIL-001 v52 ignore
+     * `prefix` and keep the old one).
+     */
+    async rotate(hex) {
+        const made = await createKey();
+        await this.#api.call('PATCH', `tenant/keys/${seg(hex)}/hash`, { body: { hash: made.hash, prefix: made.prefix } });
+        return made.key;
+    }
+    /** `DELETE /v1/tenant/keys/{hex}`: deletes the key; it stops working at once. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `tenant/keys/${seg(hex)}`);
+    }
+}

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

@@ -0,0 +1,23 @@
+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, 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';
+export type { Invocation, JmapSession, Uploaded } from '../jmap.js';

package/dist/api/index.js

@@ -0,0 +1,19 @@
+// 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, 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';