@cube-nl/dmp-sdk 0.0.0-stage → 1.0.0-rc.4

package/dist/app.d.ts

@@ -0,0 +1,87 @@
+import { type AuthorizationServerMetadata } from './auth.js';
+import { type ResourceClient } from './client.js';
+import { type AppManifest, type MockData } from './preview.js';
+import type { DmpRecord } from './types.js';
+/**
+ * `cube-app.config.json`, which the DMP writes next to the app only when it publishes an approved
+ * release. Never part of what the maker or an AI sends: its presence is what makes an app live.
+ */
+export interface CubeAppConfig {
+    /** The DMP's origin, `https://dmp.example.nl`. Also the OAuth issuer unless `issuer` says otherwise. */
+    dmpUrl: string;
+    /** The app's own public OAuth client. */
+    clientId: string;
+    /** Absolute, or relative to the page. Must equal the client's registered redirect URI. */
+    redirectUri: string;
+    /** Exactly what the reviewer approved, e.g. `['api:read', 'api:write']`. */
+    scopes: string | readonly string[];
+    /** The REST face's base URL. Default `{dmpUrl}/apps/api/v1`. */
+    apiUrl?: string;
+    /** Default `dmpUrl`. */
+    issuer?: string;
+    /** Passed to `createOAuth`: endpoints to use instead of (or on top of) discovery. */
+    metadata?: Partial<AuthorizationServerMetadata>;
+}
+export interface ConnectOptions {
+    /** Preview data: `cube.mock_data`'s output. Default: what `CubeApp.mock()` registered, else `./cube-mock.json`. */
+    mock?: MockData;
+    /**
+     * The manifest the preview holds calls against, like the live ceiling does. Default
+     * `./cube-app.json`; `false` checks nothing.
+     */
+    manifest?: AppManifest | false;
+    /** Where `./cube-app.config.json` and the other files are resolved. Default: the page's own URL. */
+    pageUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Live only. `'session'` (default): the tokens survive a reload in this tab, in
+     * `sessionStorage`, and are gone when the tab closes. `'memory'`: every reload signs in again.
+     */
+    tokenStorage?: 'session' | 'memory';
+    /** Live only: go to the DMP's sign-in right away when nobody is signed in. Default false. */
+    autoSignIn?: boolean;
+}
+export interface CubeAppUser {
+    /** The DMP's user id (the token's `sub`), or `'preview'`. Null when the token does not say. */
+    id: string | null;
+    /** Only the preview knows a name: an OAuth token from the DMP carries none. */
+    name: string | null;
+    /** What the token may do: the approved scopes. Empty in the preview. */
+    scopes: string[];
+}
+export interface CubeAppSession {
+    /** `'preview'`: mock data in this browser, no DMP. `'live'`: the real DMP, as the signed-in person. */
+    readonly mode: 'preview' | 'live';
+    /** Who is signed in, or null. In the preview a stand-in user is signed in from the start. */
+    user(): CubeAppUser | null;
+    /** Live: navigates to the DMP's sign-in (the page is gone after this). Preview: signs the stand-in in again. */
+    signIn(): Promise<void>;
+    /** Forgets the tokens in this browser. Preview: the stand-in signs out, and calls answer 401. */
+    signOut(): Promise<void>;
+    /** The same client `createClient().resources(name)` returns: list, get, create, update, delete, ... */
+    resource<T extends DmpRecord = DmpRecord>(name: string): ResourceClient<T>;
+    /** Why the last sign-in came back without a session (consent refused, say); null otherwise. */
+    readonly signInError: Error | null;
+}
+/**
+ * Starts the app. Reads `./cube-app.config.json` next to the page: absent, the app runs in the
+ * preview on mock data and makes no request to any DMP; present, it signs the end user in with
+ * OAuth (authorization code + PKCE) and talks to the DMP's REST face. The app's code is the same.
+ */
+declare function connect(options?: ConnectOptions): Promise<CubeAppSession>;
+/**
+ * Registers preview data before `connect()`, for an app that embeds its mock data in a script tag
+ * instead of shipping `cube-mock.json`. Has no effect on a live app. `null` forgets it again.
+ */
+declare function mock(data: MockData | null): void;
+/** What `cube-sdk.js` puts on `window`, and what this package exports as `CubeApp`. */
+export declare const CubeApp: Readonly<{
+    connect: typeof connect;
+    mock: typeof mock;
+    /** This SDK's version, e.g. `'1.0.0-rc.4'`. */
+    version: "1.0.0-rc.4";
+    /** The manifest `"sdk"` value this build serves. */
+    sdk: "1";
+}>;
+export type CubeAppStatic = typeof CubeApp;
+export {};

package/dist/app.js

@@ -0,0 +1,245 @@
+import { createOAuth, memoryTokenStore, } from './auth.js';
+import { createClient } from './client.js';
+import { DmpError } from './errors.js';
+import { PreviewStore } from './preview.js';
+import { MANIFEST_SDK, VERSION } from './version.js';
+const CONFIG_FILE = './cube-app.config.json';
+const MOCK_FILE = './cube-mock.json';
+const MANIFEST_FILE = './cube-app.json';
+const PREVIEW_USER = { id: 'preview', name: 'Voorbeeldgebruiker', scopes: [] };
+let registeredMock = null;
+/**
+ * Starts the app. Reads `./cube-app.config.json` next to the page: absent, the app runs in the
+ * preview on mock data and makes no request to any DMP; present, it signs the end user in with
+ * OAuth (authorization code + PKCE) and talks to the DMP's REST face. The app's code is the same.
+ */
+async function connect(options = {}) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const pageUrl = options.pageUrl ?? currentPage();
+    const config = await readJson(doFetch, resolve(CONFIG_FILE, pageUrl));
+    if (config === null) {
+        return preview(options, doFetch, pageUrl);
+    }
+    return live(asConfig(config), options, doFetch, pageUrl);
+}
+async function preview(options, doFetch, pageUrl) {
+    const mock = options.mock ?? registeredMock ?? (await readJson(doFetch, resolve(MOCK_FILE, pageUrl))) ?? {};
+    const manifest = options.manifest === false
+        ? null
+        : options.manifest ?? (await readJson(doFetch, resolve(MANIFEST_FILE, pageUrl)));
+    let signedIn = true;
+    // Signed out, the preview refuses as the API refuses a request without a token.
+    const store = new PreviewStore(mock, manifest, () => {
+        if (!signedIn) {
+            throw new DmpError(401, new Headers({ 'Content-Type': 'application/problem+json' }), {
+                type: 'https://docs.cube.nl/dmp-api/problems/token_invalid',
+                title: 'token invalid',
+                status: 401,
+                code: 'token_invalid',
+                detail: 'Unauthenticated.',
+            });
+        }
+    });
+    return {
+        mode: 'preview',
+        signInError: null,
+        user: () => (signedIn ? { ...PREVIEW_USER } : null),
+        async signIn() {
+            signedIn = true;
+        },
+        async signOut() {
+            signedIn = false;
+        },
+        resource: (name) => store.resource(name),
+    };
+}
+async function live(config, options, doFetch, pageUrl) {
+    const dmpUrl = config.dmpUrl.replace(/\/+$/, '');
+    let tokens = null;
+    const store = tracking(options.tokenStorage === 'memory' ? memoryTokenStore() : sessionTokenStore(`cube-app.tokens.${config.clientId}`), (current) => {
+        tokens = current;
+    });
+    const oauth = createOAuth({
+        issuer: config.issuer ?? dmpUrl,
+        clientId: config.clientId,
+        redirectUri: resolve(config.redirectUri, pageUrl),
+        scopes: config.scopes,
+        fetch: doFetch,
+        tokenStore: store,
+        ...(config.metadata !== undefined ? { metadata: config.metadata } : {}),
+    });
+    const client = createClient({ baseUrl: config.apiUrl ?? `${dmpUrl}/apps/api/v1`, auth: oauth, fetch: doFetch });
+    let signInError = null;
+    tokens = await store.get();
+    try {
+        await oauth.handleCallback();
+    }
+    catch (error) {
+        // A refused consent or a stale callback link is something to show, not a crash at start-up.
+        signInError = error instanceof Error ? error : new Error(String(error));
+    }
+    if (tokens === null && signInError === null && options.autoSignIn === true) {
+        await oauth.signIn();
+    }
+    return {
+        mode: 'live',
+        get signInError() {
+            return signInError;
+        },
+        user: () => (tokens === null ? null : userFrom(tokens)),
+        async signIn() {
+            signInError = null;
+            await oauth.signIn();
+        },
+        async signOut() {
+            await oauth.signOut();
+        },
+        resource: (name) => client.resources(name),
+    };
+}
+/**
+ * Who the token belongs to, read from the access token itself (cube/oauth-server issues JWTs).
+ * For display only: the DMP checks the token on every request, this SDK does not verify it.
+ */
+function userFrom(tokens) {
+    const claims = jwtClaims(tokens.accessToken);
+    const sub = claims?.sub;
+    const fromClaims = Array.isArray(claims?.scopes) ? claims.scopes.map(String) : null;
+    return {
+        id: typeof sub === 'string' || typeof sub === 'number' ? String(sub) : null,
+        name: null,
+        scopes: fromClaims ?? (tokens.scope ?? '').split(' ').filter((scope) => scope !== ''),
+    };
+}
+function jwtClaims(token) {
+    const payload = token.split('.')[1];
+    if (payload === undefined) {
+        return null;
+    }
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='));
+        const json = new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+        const claims = JSON.parse(json);
+        return claims !== null && typeof claims === 'object' ? claims : null;
+    }
+    catch {
+        return null;
+    }
+}
+function asConfig(value) {
+    const missing = ['dmpUrl', 'clientId', 'redirectUri'].filter((key) => typeof value[key] !== 'string' || value[key] === '');
+    const scopes = value.scopes;
+    if (!(typeof scopes === 'string' || (Array.isArray(scopes) && scopes.every((scope) => typeof scope === 'string')))) {
+        missing.push('scopes');
+    }
+    if (missing.length > 0) {
+        // Present but broken is a failed publish, not a preview: say so instead of showing mock data live.
+        throw new TypeError(`cube-app.config.json is incomplete: ${missing.join(', ')} missing or not a string.`);
+    }
+    return value;
+}
+/**
+ * A JSON object from the app's own origin, or null when there is none. A 404, a network failure
+ * and a page that is not a JSON object (a dev server answering every path with index.html) all
+ * mean "absent". Any other refusal is an error: a broken server must not quietly become a preview.
+ */
+async function readJson(doFetch, url) {
+    let response;
+    try {
+        response = await doFetch(url, {
+            headers: { Accept: 'application/json' },
+            ...(typeof document !== 'undefined' ? { cache: 'no-store' } : {}),
+        });
+    }
+    catch {
+        return null;
+    }
+    if (response.status === 404 || response.status === 410) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`${url} answered ${response.status}.`);
+    }
+    try {
+        const value = JSON.parse(await response.text());
+        return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function tracking(inner, onChange) {
+    return {
+        async get() {
+            const tokens = await inner.get();
+            onChange(tokens);
+            return tokens;
+        },
+        async set(tokens) {
+            await inner.set(tokens);
+            onChange(tokens);
+        },
+    };
+}
+/** sessionStorage, falling back to memory where storage is blocked (a sandboxed iframe). */
+function sessionTokenStore(key) {
+    const storage = (() => {
+        try {
+            return globalThis.sessionStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (storage === null) {
+        return memoryTokenStore();
+    }
+    return {
+        get() {
+            try {
+                const raw = storage.getItem(key);
+                return raw === null ? null : JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        set(tokens) {
+            try {
+                if (tokens === null) {
+                    storage.removeItem(key);
+                }
+                else {
+                    storage.setItem(key, JSON.stringify(tokens));
+                }
+            }
+            catch {
+                // Storage full or blocked: the session lasts as long as the page.
+            }
+        },
+    };
+}
+function currentPage() {
+    const page = globalThis;
+    return page.document?.baseURI ?? page.location?.href ?? 'http://localhost/';
+}
+function resolve(path, pageUrl) {
+    return new URL(path, pageUrl).href;
+}
+/**
+ * Registers preview data before `connect()`, for an app that embeds its mock data in a script tag
+ * instead of shipping `cube-mock.json`. Has no effect on a live app. `null` forgets it again.
+ */
+function mock(data) {
+    registeredMock = data;
+}
+/** What `cube-sdk.js` puts on `window`, and what this package exports as `CubeApp`. */
+export const CubeApp = Object.freeze({
+    connect,
+    mock,
+    /** This SDK's version, e.g. `'1.0.0-rc.4'`. */
+    version: VERSION,
+    /** The manifest `"sdk"` value this build serves. */
+    sdk: MANIFEST_SDK,
+});

package/dist/auth.d.ts

@@ -0,0 +1,117 @@
+/**
+ * How the client gets a token. `bearer()` and `createOAuth()` both implement it; so can your own
+ * object, for a token that comes from somewhere else entirely.
+ */
+export interface AuthStrategy {
+    /** The bearer token for the next request, or null to send none. Read on every request. */
+    getAccessToken(): string | null | Promise<string | null>;
+    /** Called once on a 401. Resolve true after getting a new token to have the request retried once. */
+    onUnauthorized?(): boolean | Promise<boolean>;
+}
+export type TokenSource = string | (() => string | null | undefined | Promise<string | null | undefined>);
+/**
+ * A fixed token: a personal token (`$user->createToken(...)`) or an API-client token. Pass a
+ * function to read it fresh on every call. Never hardcode one in code that reaches a browser bundle.
+ */
+export declare function bearer(token: TokenSource): AuthStrategy;
+/** RFC 8414, the fields this SDK reads. */
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    scopes_supported?: string[];
+    code_challenge_methods_supported?: string[];
+    grant_types_supported?: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    [key: string]: unknown;
+}
+export interface Tokens {
+    accessToken: string;
+    refreshToken: string | null;
+    /** Epoch milliseconds; null when the server gave no `expires_in`. */
+    expiresAt: number | null;
+    scope: string | null;
+}
+/** Where the tokens live. Memory by default; bring your own only as a deliberate choice. */
+export interface TokenStore {
+    get(): Tokens | null | Promise<Tokens | null>;
+    set(tokens: Tokens | null): void | Promise<void>;
+}
+/** Where the PKCE verifier and state survive the redirect. sessionStorage in a browser by default. */
+export interface KeyValueStore {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface OAuthOptions {
+    /** The DMP's origin, e.g. `https://dmp.example.nl`. Discovery is read from `{issuer}/.well-known/...`. */
+    issuer: string;
+    clientId: string;
+    /** Must equal a redirect URI registered for the client exactly: scheme, host, port and path. */
+    redirectUri: string;
+    /** `api:read`, `api:write`. `api:write` does not include `api:read`; ask for both when you need both. */
+    scopes: string | readonly string[];
+    /**
+     * Only for a confidential client on a server (Node). Never in a browser: anything in the bundle
+     * is public. A browser app is a public client, and PKCE is its proof.
+     */
+    clientSecret?: string;
+    /**
+     * The whole document (it must name `authorization_endpoint` and `token_endpoint`) to skip
+     * discovery, or only the members you want to override on top of what discovery returns: for
+     * example `{ token_endpoint: '/oauth/token' }` to send the code exchange through a dev-server
+     * proxy, because the DMP's token endpoint answers no CORS.
+     */
+    metadata?: Partial<AuthorizationServerMetadata>;
+    fetch?: typeof fetch;
+    tokenStore?: TokenStore;
+    pendingStore?: KeyValueStore;
+    /** Refresh this many seconds before the access token expires. Default 30. */
+    refreshLeewaySeconds?: number;
+}
+export interface OAuthSession extends AuthStrategy {
+    discover(): Promise<AuthorizationServerMetadata>;
+    /** The URL to send the person to. Stores the verifier and state for `handleCallback()`. */
+    authorizationUrl(options?: {
+        state?: string;
+        extraParams?: Record<string, string>;
+    }): Promise<string>;
+    /** Browser only: navigates to `authorizationUrl()`. The page is gone after this. */
+    signIn(options?: {
+        extraParams?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * On the redirect URI. Returns null when the URL is not a callback, so it can run on every
+     * page load. In a browser it removes `code` and `state` from the address bar.
+     */
+    handleCallback(url?: string | URL): Promise<Tokens | null>;
+    refresh(): Promise<Tokens>;
+    getTokens(): Promise<Tokens | null>;
+    setTokens(tokens: Tokens | null): Promise<void>;
+    signOut(): Promise<void>;
+}
+export interface RegistrationRequest {
+    clientName: string;
+    redirectUris: readonly string[];
+    [extra: string]: unknown;
+}
+/**
+ * OAuth 2.1 authorization code with PKCE (S256) against cube/oauth-server.
+ *
+ * The access token lives in memory unless you pass a `tokenStore`. What survives the redirect is
+ * the verifier and the state, in sessionStorage: useless without the code, and removed as soon as
+ * the callback is handled.
+ */
+export declare function createOAuth(options: OAuthOptions): OAuthSession;
+/**
+ * RFC 7591 dynamic client registration, when the DMP turned it on (`registration_endpoint` is then
+ * in discovery). Returns the registration response, with `client_id`.
+ */
+export declare function registerClient(server: AuthorizationServerMetadata, request: RegistrationRequest, doFetch?: typeof fetch): Promise<Record<string, unknown> & {
+    client_id: string;
+}>;
+export declare function discoverMetadata(issuer: string, doFetch?: typeof fetch): Promise<AuthorizationServerMetadata>;
+export declare function memoryTokenStore(initial?: Tokens | null): TokenStore;
+export declare function memoryKeyValueStore(): KeyValueStore;
+export declare function base64url(buffer: ArrayBuffer | Uint8Array): string;