@adukilabs/sdk 0.0.0-stage → 0.1.2

package/dist/dpop.js

@@ -0,0 +1,156 @@
+// DPoP (RFC 9449; ADK-AUTH-001 section 10, aduki-kt Dpop.kt) with ES256 and a
+// non-extractable WebCrypto P-256 key. The private key never leaves the
+// key store: it can only sign. It is persisted as a CryptoKey in IndexedDB
+// (or any storage that structured-clones keys), or kept in memory only.
+//
+// - A request with no Authorization (sign-in, refresh) gets a proof without `ath`.
+// - A request whose token is bound to this key (`cnf.jkt` equals the thumbprint)
+//   is sent as `Authorization: DPoP <token>` with a proof carrying `ath`.
+// - Any other credential is left untouched.
+// - A DPoP-Nonce from the server is remembered per origin; a 401 or 400
+//   carrying a nonce is retried once with it.
+import { claims, encode, encodeText } from './base64.js';
+import { ProtocolError } from './errors.js';
+const ALG = { name: 'ECDSA', namedCurve: 'P-256' };
+const KEY = 'dpop.key';
+export class Dpop {
+    #pair;
+    #jwk;
+    #thumbprint;
+    #clock;
+    #nonces = new Map();
+    /** Use `Dpop.load` or `Dpop.generate`. */
+    constructor(pair, jwk, thumbprint, clock = Date.now) {
+        this.#pair = pair;
+        this.#jwk = jwk;
+        this.#thumbprint = thumbprint;
+        this.#clock = clock;
+    }
+    /** Generates a new non-extractable key. */
+    static async generate(options = {}) {
+        const pair = await globalThis.crypto.subtle.generateKey(ALG, false, ['sign', 'verify']);
+        return Dpop.from(pair, options);
+    }
+    /** Wraps an existing key pair (its private key must be a P-256 ECDSA signing key). */
+    static async from(pair, options = {}) {
+        const exported = await globalThis.crypto.subtle.exportKey('jwk', pair.publicKey);
+        const jwk = { kty: 'EC', crv: 'P-256', x: exported.x, y: exported.y };
+        return new Dpop(pair, jwk, await thumbprint(jwk), options.clock);
+    }
+    /**
+     * Loads the key from `storage` (key `dpop.key`), or generates and saves one.
+     * Two tabs loading at the same time must end with the same key, so the
+     * read-or-create runs under a Web Lock when the browser has one (a key made by
+     * a tab that lost the race would otherwise be overwritten and its tokens
+     * bound to a key nobody holds any more).
+     */
+    static async load(storage, options = {}) {
+        const locks = options.locks === undefined ? globalThis.navigator?.locks : options.locks;
+        const once = async () => {
+            const saved = await storage.get(KEY);
+            if (saved?.privateKey && saved?.publicKey)
+                return Dpop.from(saved, options);
+            const made = await Dpop.generate(options);
+            await storage.set(KEY, made.#pair);
+            return made;
+        };
+        return locks ? locks.request('aduki-dpop-key', once) : once();
+    }
+    /** The key's thumbprint (RFC 7638), as stored by Aduki ID in `cnf.jkt`. */
+    get thumbprint() {
+        return this.#thumbprint;
+    }
+    /** The public JWK (kty, crv, x, y). */
+    get jwk() {
+        return { ...this.#jwk };
+    }
+    /**
+     * One proof for `method` on `url` (query and fragment are not signed). Pass
+     * `access` to bind the proof to a token with `ath`, and `nonce` when the
+     * server asked for one.
+     */
+    proof({ method, url, access = null, nonce = null }) {
+        return this.sign({ htm: method.toUpperCase(), htu: String(url).split('#')[0].split('?')[0], access, nonce });
+    }
+    /**
+     * One proof with `htm` and `htu` exactly as given (no upper-casing, no URL
+     * trimming), for proofs outside HTTP: the Chats handshake signs
+     * `htm = "ae09"`, `htu = "identity.response"` with the challenge as `nonce`.
+     */
+    async sign({ htm, htu, access = null, nonce = null }) {
+        const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: this.#jwk };
+        const body = {
+            htm,
+            htu,
+            iat: Math.floor(this.#clock() / 1000),
+            jti: encode(globalThis.crypto.getRandomValues(new Uint8Array(16))),
+        };
+        if (access)
+            body.ath = await athash(access);
+        if (nonce)
+            body.nonce = nonce;
+        const input = `${encodeText(JSON.stringify(header))}.${encodeText(JSON.stringify(body))}`;
+        // WebCrypto ECDSA returns the raw r||s form that JWS ES256 uses.
+        const signature = await globalThis.crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, this.#pair.privateKey, new TextEncoder().encode(input));
+        return `${input}.${encode(signature)}`;
+    }
+    /**
+     * Returns `request` with its DPoP header and scheme applied by the rules above.
+     * @param nonce defaults to the one remembered for the origin
+     */
+    async apply(request, nonce = this.#nonces.get(new URL(request.url).origin) ?? null) {
+        const sent = request.headers.get('Authorization') ?? '';
+        const [scheme, token] = sent.split(' ');
+        const headers = new Headers(request.headers);
+        if (sent.trim() === '') {
+            headers.set('DPoP', await this.proof({ method: request.method, url: request.url, nonce }));
+        }
+        else if ((scheme === 'Bearer' || scheme === 'DPoP') && token && this.bound(token)) {
+            headers.set('Authorization', `DPoP ${token}`);
+            headers.set('DPoP', await this.proof({ method: request.method, url: request.url, access: token, nonce }));
+        }
+        else {
+            return request;
+        }
+        return new Request(request, { headers });
+    }
+    /** True when the access token (a JWT) is bound to this key. */
+    bound(token) {
+        return claims(token).cnf?.jkt === this.#thumbprint;
+    }
+    /** A fetch that applies DPoP and retries once on a fresh `DPoP-Nonce`. */
+    wrap(inner = (...args) => globalThis.fetch(...args)) {
+        return async (input, init) => {
+            const request = new Request(input, init);
+            const spare = request.clone();
+            const response = await inner(await this.apply(request));
+            const origin = new URL(request.url).origin;
+            const nonce = response.headers.get('DPoP-Nonce');
+            if (nonce)
+                this.#nonces.set(origin, nonce);
+            if (!nonce || (response.status !== 401 && response.status !== 400))
+                return response;
+            await response.arrayBuffer().catch(() => { });
+            const retry = await inner(await this.apply(spare, nonce));
+            const next = retry.headers.get('DPoP-Nonce');
+            if (next)
+                this.#nonces.set(origin, next);
+            return retry;
+        };
+    }
+}
+/** base64url SHA-256 of the access token (`ath`) */
+async function athash(token) {
+    return encode(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(token)));
+}
+/** The RFC 7638 JWK thumbprint of an EC or OKP public key. */
+export async function thumbprint(jwk) {
+    let canonical;
+    if (jwk.kty === 'EC')
+        canonical = { crv: jwk.crv, kty: 'EC', x: jwk.x, y: jwk.y };
+    else if (jwk.kty === 'OKP')
+        canonical = { crv: jwk.crv, kty: 'OKP', x: jwk.x };
+    else
+        throw new ProtocolError(`Unsupported key type ${jwk.kty}`);
+    return encode(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(canonical))));
+}

package/dist/envelope.d.ts

@@ -0,0 +1,59 @@
+import type { AdukiError } from './errors.js';
+/** Stable error kinds clients switch on (ADK-NET-001 section 4). */
+export declare const kinds: Readonly<{
+    missing: "auth.missing";
+    invalid: "auth.invalid";
+    stale: "auth.stale";
+    stepup: "auth.stepup";
+    denied: "access.denied";
+    input: "input.invalid";
+    absent: "entity.missing";
+    conflict: "entity.conflict";
+    limited: "rate.limited";
+    reset: "sync.reset";
+    quota: "quota.exceeded";
+    plan: "plan.limit";
+    unavailable: "auth.unavailable";
+    server: "server.error";
+}>;
+/** A parsed envelope: an object with a `success` field (the rest is the server's). */
+export type Envelope = Record<string, any>;
+/** `{status, kind, message, details}` of a failure envelope. */
+export interface Failure {
+    status: number;
+    kind: string;
+    message: string;
+    details: unknown;
+}
+/** The parsed envelope, or null when the body is not one. */
+export declare function parse(body: string): Envelope | null;
+/**
+ * The `data` of a success envelope, or the parsed body itself when it is not an
+ * envelope (servers from before it pass through unchanged).
+ */
+export declare function data(body: string): any;
+/** `{status, kind, message, details}` from a failure envelope, or null. */
+export declare function failure(body: string): Failure | null;
+/**
+ * The typed error of a failed answer whose body was `body` (see
+ * `errors.refusal`): the envelope's kind, message and details, the
+ * `Retry-After` header, and with `problem` the `type` and `detail` of an
+ * RFC 7807 problem document (JMAP request-level errors) when the body is no
+ * envelope. A body that is neither (the gateway's plain 429 or 503) leaves
+ * the status alone to speak.
+ * @param what names the call in error messages
+ */
+export declare function rejection(response: Response, body: string, what: string, options?: {
+    problem?: boolean;
+}): AdukiError;
+/**
+ * Reads a fetch Response as an envelope. A 2xx answer returns its `data`.
+ * A failure throws the typed error of `rejection`: UnauthorizedError for a
+ * 401 (`kind: message`), otherwise a NetworkError (or one of its subclasses:
+ * RateLimitedError, StepUpError, LimitError, SyncResetError, ServerError)
+ * with the HTTP status, the kind, the details and `retryAfter`.
+ * @param what names the call in error messages
+ */
+export declare function read(response: Response, what: string): Promise<any>;
+/** True for the `auth.stale` kind (rights changed, renew the token). */
+export declare function isStale(error: unknown): boolean;

package/dist/envelope.js

@@ -0,0 +1,114 @@
+// The Aduki REST envelope (ADK-NET-001 section 3):
+// {success: true, data} or {success: false, error: {status, kind, message, details}}.
+import { NetworkError, UnauthorizedError, refusal } from './errors.js';
+/** Stable error kinds clients switch on (ADK-NET-001 section 4). */
+export const kinds = Object.freeze({
+    missing: 'auth.missing',
+    invalid: 'auth.invalid',
+    stale: 'auth.stale',
+    stepup: 'auth.stepup',
+    denied: 'access.denied',
+    input: 'input.invalid',
+    absent: 'entity.missing',
+    conflict: 'entity.conflict',
+    limited: 'rate.limited',
+    reset: 'sync.reset',
+    quota: 'quota.exceeded',
+    plan: 'plan.limit',
+    unavailable: 'auth.unavailable',
+    server: 'server.error',
+});
+/** The parsed envelope, or null when the body is not one. */
+export function parse(body) {
+    const text = String(body ?? '').trimStart();
+    if (!text.startsWith('{'))
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === 'object' && 'success' in value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `data` of a success envelope, or the parsed body itself when it is not an
+ * envelope (servers from before it pass through unchanged).
+ */
+export function data(body) {
+    const envelope = parse(body);
+    if (!envelope || envelope.success !== true) {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    return envelope.data ?? null;
+}
+/** `{status, kind, message, details}` from a failure envelope, or null. */
+export function failure(body) {
+    const error = parse(body)?.error;
+    if (!error || typeof error !== 'object')
+        return null;
+    return {
+        status: Number(error.status) || 0,
+        kind: String(error.kind ?? ''),
+        message: String(error.message ?? ''),
+        details: error.details,
+    };
+}
+/**
+ * The typed error of a failed answer whose body was `body` (see
+ * `errors.refusal`): the envelope's kind, message and details, the
+ * `Retry-After` header, and with `problem` the `type` and `detail` of an
+ * RFC 7807 problem document (JMAP request-level errors) when the body is no
+ * envelope. A body that is neither (the gateway's plain 429 or 503) leaves
+ * the status alone to speak.
+ * @param what names the call in error messages
+ */
+export function rejection(response, body, what, options = {}) {
+    const error = failure(body);
+    let kind = error?.kind ?? '';
+    let message = error?.message ?? '';
+    let details = error?.details;
+    if (!error && options.problem) {
+        try {
+            const problem = JSON.parse(body);
+            if (problem && typeof problem === 'object') {
+                kind = String(problem.type ?? '');
+                message = String(problem.detail ?? problem.title ?? '');
+                details = problem;
+            }
+        }
+        catch {
+            // not JSON: the status says it
+        }
+    }
+    return refusal({ status: response.status, kind, message, details, retry: response.headers.get('Retry-After'), what });
+}
+/**
+ * Reads a fetch Response as an envelope. A 2xx answer returns its `data`.
+ * A failure throws the typed error of `rejection`: UnauthorizedError for a
+ * 401 (`kind: message`), otherwise a NetworkError (or one of its subclasses:
+ * RateLimitedError, StepUpError, LimitError, SyncResetError, ServerError)
+ * with the HTTP status, the kind, the details and `retryAfter`.
+ * @param what names the call in error messages
+ */
+export async function read(response, what) {
+    const body = await response.text();
+    if (!response.ok)
+        throw rejection(response, body, what);
+    const envelope = parse(body);
+    if (!envelope)
+        throw new NetworkError(`Empty response from ${what}`, { status: response.status });
+    if (envelope.data === undefined || envelope.data === null) {
+        throw new NetworkError(`Empty response from ${what}`, { status: response.status });
+    }
+    return envelope.data;
+}
+/** True for the `auth.stale` kind (rights changed, renew the token). */
+export function isStale(error) {
+    return error instanceof UnauthorizedError && error.kind === kinds.stale;
+}

package/dist/errors.d.ts

@@ -0,0 +1,165 @@
+/** Base class of every error the SDK throws. */
+export declare class AdukiError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The options of NetworkError and its subclasses. */
+export interface NetworkErrorOptions {
+    status?: number | undefined;
+    kind?: string | undefined;
+    details?: unknown;
+    /** seconds to wait before trying again (`Retry-After`, or the envelope's `details`) */
+    retryAfter?: number | undefined;
+    cause?: unknown;
+}
+/**
+ * Transport failure or a non-2xx answer that is not a 401. `status` is the
+ * HTTP status when there was one (undefined: the server was not reached).
+ * `retryAfter` holds the seconds the server asked to wait, when it said.
+ * The subclasses below name the answers a client acts on; see `refusal`.
+ */
+export declare class NetworkError extends AdukiError {
+    status: number | undefined;
+    kind: string;
+    details: unknown;
+    retryAfter: number | undefined;
+    constructor(message: string, options?: NetworkErrorOptions);
+}
+/** `429`: too many requests (`rate.limited`, `mail.queue_busy`, or the gateway's plain 429). Wait `retryAfter` seconds when given. */
+export declare class RateLimitedError extends NetworkError {
+}
+/** `403 auth.stepup`: the action needs a fresh second factor; the session stays valid. */
+export declare class StepUpError extends NetworkError {
+}
+/**
+ * A package limit or quota was reached: `403 plan.limit` or `507 quota.exceeded`.
+ * `key`, `limit` and `used` come from the details when the server sent them.
+ */
+export declare class LimitError extends NetworkError {
+    key: string;
+    limit: number | undefined;
+    used: number | undefined;
+    constructor(message: string, options?: NetworkErrorOptions);
+}
+/** `410 sync.reset`: the sync token is no longer known; sync again without one. */
+export declare class SyncResetError extends NetworkError {
+}
+/** A `5xx` answer (`server.error`, `auth.unavailable`, a gateway 502, 503 or 504); `retryAfter` when the server said. */
+export declare class ServerError extends NetworkError {
+}
+/** The kinds after which the session is over and its tokens are useless (aduki-kt `Unauthorized.ENDED`). */
+export declare const ENDED: readonly string[];
+/** The server refused the credentials (401): wrong password, spent refresh token, stale token. */
+export declare class UnauthorizedError extends AdukiError {
+    status: number;
+    kind: string;
+    details: unknown;
+    constructor(message: string, options?: {
+        kind?: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+    /**
+     * True when the kind says the session is over (`auth.invalid`,
+     * `auth.reused`, `auth.revoked`, `auth.expired`); false for other kinds
+     * (`auth.factor`, `auth.stale`, `auth.dpop`) and for a 401 without one.
+     */
+    get ended(): boolean;
+}
+/**
+ * `401 auth.dpop` or `401 auth.nonce`: the DPoP proof was refused (a key or
+ * clock problem), not the credentials (aduki-kt `AdukiException.Proof`). A
+ * subclass of UnauthorizedError, so existing `instanceof` checks still match.
+ */
+export declare class ProofError extends UnauthorizedError {
+}
+/**
+ * `401` with `details.reason = "token.required"`: the server needs the Aduki
+ * ID token and its proof with the request (the Chats handshake on an Aduki
+ * deployment). A client that cannot send them is too old: tell the user to
+ * update instead of retrying.
+ */
+export declare class TokenRequiredError extends UnauthorizedError {
+}
+/**
+ * `401` with `details.reason = "session.expired"` or `"session.ended"`: the
+ * Chats session is over (its time ran out, or Aduki ID ended the sign-in
+ * session that authorized it). Repeat the handshake; after `session.ended`
+ * that needs a current token (the person may have to sign in again).
+ */
+export declare class SessionEndedError extends UnauthorizedError {
+    /** `session.expired` or `session.ended` */
+    get reason(): string;
+}
+/**
+ * `403` with `details.reason = "subject"` (the token is for another account
+ * than the device's) or `"jkt.mismatch"` (the device is bound to another
+ * Aduki ID key than the token's). Retrying with the same key does not help.
+ */
+export declare class IdentityMismatchError extends NetworkError {
+    /** `subject` or `jkt.mismatch` */
+    get reason(): string;
+}
+/**
+ * `403 access.denied` with `details.reason = "client"`: the route is not for
+ * a program. A workspace's service client (machine access) is refused where
+ * only a person may act: in Store shares, links, devices, reports, search,
+ * tickets and the change feed; in Space the strict and money routes. Another
+ * token does not help: the route needs a person signed in.
+ */
+export declare class ClientRefusedError extends NetworkError {
+    /** always `client` */
+    get reason(): string;
+}
+/**
+ * A 2xx authentication answer that could not be used. `refresh` carries a
+ * rotated refresh token the answer did include, so callers never lose a token
+ * the server already swapped in.
+ */
+export declare class AuthError extends AdukiError {
+    refresh: string;
+    constructor(message: string, options?: {
+        refresh?: string;
+        cause?: unknown;
+    });
+}
+/** A protocol violation: bad state, issuer mismatch, bad id token, missing field. */
+export declare class ProtocolError extends AdukiError {
+}
+/** A storage backend failed. */
+export declare class StorageError extends AdukiError {
+}
+/** What `refusal` needs to know of a failed answer. */
+export interface Refused {
+    /** the HTTP status */
+    status: number;
+    /** the envelope's kind, or the problem document's type ('' when none) */
+    kind?: string | undefined;
+    /** the server's message ('' or absent: `HTTP <status>`) */
+    message?: string | undefined;
+    details?: unknown;
+    /** the `Retry-After` header, as sent */
+    retry?: string | null | undefined;
+    /** names the call in the message (`<what> failed: ...`) */
+    what?: string | undefined;
+}
+/**
+ * The one mapping from a refused answer to a typed error, used by every
+ * service module. A 401 is UnauthorizedError (`auth.dpop`, `auth.nonce`:
+ * ProofError; `details.reason` `token.required`: TokenRequiredError;
+ * `session.expired`, `session.ended`: SessionEndedError); a 429
+ * RateLimitedError; a 403 with `details.reason` `subject` or `jkt.mismatch`
+ * IdentityMismatchError; a 403 with `details.reason` `client`
+ * ClientRefusedError; `403 auth.stepup` StepUpError;
+ * `plan.limit` and `quota.exceeded` LimitError; `sync.reset` SyncResetError;
+ * a 5xx ServerError; anything else NetworkError. Every one but the 401s is a
+ * NetworkError with `status`, `kind`, `details` and `retryAfter` (from the
+ * `Retry-After` header, else `details.retry_after` or `details.retry`).
+ */
+export declare function refusal({ status, kind, message, details, retry, what }: Refused): AdukiError;
+/**
+ * The seconds of a `Retry-After` value (delta seconds or an HTTP date), or
+ * undefined when absent or unreadable. Never negative.
+ */
+export declare function retryAfter(value: string | null | undefined, now?: number): number | undefined;