@permute/sdk 0.6.0 → 0.8.0

package/dist/auth/oauth.d.ts

@@ -0,0 +1,64 @@
+import { PermuteClient } from '../client.js';
+import { type CredentialStore, type LoginCredentials } from './store.js';
+export { SystemCredentialStore, type CredentialStore, type LoginCredentials } from './store.js';
+export declare const DEFAULT_ISSUER = "https://auth.permute.ai";
+export declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export interface OAuthOptions {
+    issuer?: string;
+    apiUrl?: string;
+    store?: CredentialStore;
+    fetch?: typeof fetch;
+}
+export declare class OAuthLogin {
+    readonly issuer: string;
+    readonly apiUrl: string;
+    private readonly store;
+    private readonly fetchImpl;
+    constructor(options?: OAuthOptions);
+    private endpoint;
+    private post;
+    private tokens;
+    private persist;
+    beginDevice(): Promise<{
+        deviceCode: string;
+        userCode: string;
+        url: string;
+        expiresIn: number;
+        expiresAt: number;
+        interval: number;
+    }>;
+    finishDevice(request: Awaited<ReturnType<OAuthLogin['beginDevice']>>, signal?: AbortSignal): Promise<{
+        issuer: string;
+        apiUrl: string;
+        workspaceId: string | undefined;
+        organizationId: string;
+        sessionId: string;
+        access: string;
+        refresh: string;
+        expiresAt: number;
+    }>;
+    beginBrowser(redirectURI: string): {
+        url: string;
+        verifier: string;
+        state: string;
+        redirectURI: string;
+    };
+    finishBrowser(request: ReturnType<OAuthLogin['beginBrowser']>, callback: URL): Promise<{
+        issuer: string;
+        apiUrl: string;
+        workspaceId: string | undefined;
+        organizationId: string;
+        sessionId: string;
+        access: string;
+        refresh: string;
+        expiresAt: number;
+    }>;
+    credentials(): Promise<LoginCredentials>;
+    client(): Promise<PermuteClient>;
+    logout(): Promise<void>;
+    private revoke;
+}
+export declare class OAuthLoginError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}

package/dist/auth/oauth.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { createHash, randomBytes } from 'node:crypto';
+import { setTimeout } from 'node:timers/promises';
+import { PermuteClient } from '../client.js';
+import { SystemCredentialStore } from './store.js';
+export { SystemCredentialStore } from './store.js';
+export const DEFAULT_ISSUER = 'https://auth.permute.ai';
+const CLIENT_ID = 'permute-cli';
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const TokensSchema = z.object({
+    access_token: z.string().min(1),
+    refresh_token: z.string().min(1),
+    expires_in: z.number().int().positive(),
+    workspace_id: z.string().min(1).optional(),
+    organization_id: z.string().min(1),
+    session_id: z.string().min(1),
+});
+const DeviceSchema = z.object({
+    device_code: z.string().min(1),
+    user_code: z.string().min(1),
+    verification_uri_complete: z.string().url(),
+    expires_in: z.number().int().positive(),
+    interval: z.number().int().min(5),
+});
+export class OAuthLogin {
+    issuer;
+    apiUrl;
+    store;
+    fetchImpl;
+    constructor(options = {}) {
+        this.issuer = this.endpoint(options.issuer ?? DEFAULT_ISSUER);
+        this.apiUrl = this.endpoint(options.apiUrl ?? 'https://api.permute.ai');
+        this.store = options.store ?? new SystemCredentialStore(this.issuer);
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    endpoint(value) {
+        const url = new URL(value);
+        if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== '/')
+            throw new Error('Use an HTTPS origin (or loopback for local development).');
+        return url.origin;
+    }
+    async post(path, input) {
+        const response = await this.fetchImpl(`${this.issuer}${path}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(input),
+            signal: AbortSignal.timeout(15_000),
+            redirect: 'error',
+        });
+        const result = await response.json();
+        if (!response.ok) {
+            const error = z.object({ error: z.string().max(100) }).safeParse(result);
+            throw new OAuthLoginError(error.success ? error.data.error : 'login_failed');
+        }
+        return result;
+    }
+    tokens(value) {
+        const parsed = TokensSchema.safeParse(value);
+        if (!parsed.success)
+            throw new Error('Invalid credential response');
+        return parsed.data;
+    }
+    async persist(tokens) {
+        const credentials = {
+            issuer: this.issuer,
+            apiUrl: this.apiUrl,
+            workspaceId: tokens.workspace_id,
+            organizationId: tokens.organization_id,
+            sessionId: tokens.session_id,
+            access: tokens.access_token,
+            refresh: tokens.refresh_token,
+            expiresAt: Date.now() + tokens.expires_in * 1000,
+        };
+        try {
+            const previous = await this.store.read();
+            if (previous && previous.sessionId !== tokens.session_id)
+                await this.revoke(previous.refresh);
+            await this.store.write(credentials);
+        }
+        catch (error) {
+            // Failed replacement or secure storage must not orphan the new credential.
+            await this.revoke(tokens.refresh_token);
+            throw error;
+        }
+        return credentials;
+    }
+    async beginDevice() {
+        const parsed = DeviceSchema.safeParse(await this.post('/cli/device/authorization', { client_id: CLIENT_ID, scope: 'workspace' }));
+        if (!parsed.success)
+            throw new Error('Invalid device login response');
+        const result = parsed.data;
+        return {
+            deviceCode: result.device_code,
+            userCode: result.user_code,
+            url: result.verification_uri_complete,
+            expiresIn: result.expires_in,
+            expiresAt: Date.now() + result.expires_in * 1000,
+            interval: result.interval,
+        };
+    }
+    async finishDevice(request, signal) {
+        const deadline = request.expiresAt;
+        let interval = request.interval;
+        while (Date.now() < deadline) {
+            await setTimeout(interval * 1000, undefined, { signal });
+            try {
+                return await this.store.exclusive(async () => {
+                    const tokens = this.tokens(await this.post('/token', {
+                        client_id: CLIENT_ID,
+                        grant_type: DEVICE_GRANT,
+                        device_code: request.deviceCode,
+                    }));
+                    return this.persist(tokens);
+                });
+            }
+            catch (error) {
+                if (!(error instanceof OAuthLoginError))
+                    throw error;
+                if (error.code === 'authorization_pending')
+                    continue;
+                if (error.code === 'slow_down') {
+                    interval += 5;
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new OAuthLoginError('expired_token');
+    }
+    beginBrowser(redirectURI) {
+        const verifier = randomBytes(32).toString('base64url');
+        const state = randomBytes(32).toString('base64url');
+        const url = new URL(`${this.issuer}/authorize`);
+        url.search = new URLSearchParams({
+            client_id: CLIENT_ID,
+            scope: 'workspace',
+            response_type: 'code',
+            redirect_uri: redirectURI,
+            state,
+            code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+            code_challenge_method: 'S256',
+        }).toString();
+        return { url: url.toString(), verifier, state, redirectURI };
+    }
+    async finishBrowser(request, callback) {
+        if (callback.origin + callback.pathname !== request.redirectURI ||
+            callback.searchParams.get('state') !== request.state)
+            throw new Error('Login callback did not match this request');
+        if (callback.searchParams.has('error'))
+            throw new OAuthLoginError('access_denied');
+        const code = callback.searchParams.get('code');
+        if (!code)
+            throw new Error('Login callback has no authorization code');
+        return this.store.exclusive(async () => {
+            const tokens = this.tokens(await this.post('/token', {
+                client_id: CLIENT_ID,
+                grant_type: 'authorization_code',
+                redirect_uri: request.redirectURI,
+                code_verifier: request.verifier,
+                code,
+            }));
+            return this.persist(tokens);
+        });
+    }
+    async credentials() {
+        return this.store.exclusive(async () => {
+            const current = await this.store.read();
+            if (!current || current.apiUrl !== this.apiUrl)
+                throw new Error('No login for this server. Run permute auth login.');
+            if (current.expiresAt > Date.now() + 60_000)
+                return current;
+            const tokens = this.tokens(await this.post('/token', {
+                client_id: CLIENT_ID,
+                grant_type: 'refresh_token',
+                refresh_token: current.refresh,
+            }));
+            return this.persist(tokens);
+        });
+    }
+    async client() {
+        const credentials = await this.credentials();
+        return new PermuteClient({
+            baseUrl: this.apiUrl,
+            fetch: this.fetchImpl,
+            workspaceId: credentials.workspaceId,
+            accessToken: async () => (await this.credentials()).access,
+        });
+    }
+    async logout() {
+        await this.store.exclusive(async () => {
+            const current = await this.store.read();
+            if (!current)
+                return;
+            // Keep the local record on failure so revocation can be retried.
+            await this.revoke(current.refresh);
+            await this.store.remove();
+        });
+    }
+    async revoke(refresh) {
+        const response = await this.fetchImpl(`${this.issuer}/revoke`, {
+            method: 'POST',
+            body: new URLSearchParams({ client_id: CLIENT_ID, token: refresh }),
+            signal: AbortSignal.timeout(15_000),
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw new Error('Could not revoke login. Retry logout when connected.');
+    }
+}
+export class OAuthLoginError extends Error {
+    code;
+    constructor(code) {
+        super(`Login failed (${code}). Run permute auth login to try again.`);
+        this.code = code;
+    }
+}

package/dist/auth/store.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+declare const LoginCredentialsSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    apiUrl: z.ZodString;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodString;
+    access: z.ZodString;
+    refresh: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type LoginCredentials = z.infer<typeof LoginCredentialsSchema>;
+export interface CredentialStore {
+    read(): Promise<LoginCredentials | null>;
+    write(value: LoginCredentials): Promise<void>;
+    remove(): Promise<void>;
+    exclusive<T>(run: () => Promise<T>): Promise<T>;
+}
+/** Tokens never fall back to a plaintext file. The disk lock contains no credentials. */
+export declare class SystemCredentialStore implements CredentialStore {
+    private readonly issuer;
+    private readonly account;
+    constructor(issuer: string);
+    private entry;
+    read(): Promise<{
+        issuer: string;
+        apiUrl: string;
+        workspaceId?: string | undefined;
+        organizationId?: string | undefined;
+        sessionId: string;
+        access: string;
+        refresh: string;
+        expiresAt: number;
+    } | null>;
+    write(value: LoginCredentials): Promise<void>;
+    remove(): Promise<void>;
+    exclusive<T>(run: () => Promise<T>): Promise<T>;
+}
+export {};

package/dist/auth/store.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdir, rm } from 'node:fs/promises';
+import { setTimeout } from 'node:timers/promises';
+const LoginCredentialsSchema = z.object({
+    issuer: z.string().url(),
+    apiUrl: z.string().url(),
+    workspaceId: z.string().min(1).optional(),
+    organizationId: z.string().min(1).optional(),
+    sessionId: z.string().min(1),
+    access: z.string().min(1),
+    refresh: z.string().min(1),
+    expiresAt: z.number().finite(),
+});
+/** Tokens never fall back to a plaintext file. The disk lock contains no credentials. */
+export class SystemCredentialStore {
+    issuer;
+    account;
+    constructor(issuer) {
+        this.issuer = issuer;
+        this.account = createHash('sha256').update(issuer).digest('hex');
+    }
+    async entry() {
+        const { AsyncEntry } = await import('@napi-rs/keyring');
+        return new AsyncEntry('permute-cli', this.account, { linux: { store: 'secret-service' } });
+    }
+    async read() {
+        const value = await (await this.entry()).getPassword();
+        if (!value)
+            return null;
+        const parsed = LoginCredentialsSchema.safeParse(JSON.parse(value));
+        if (!parsed.success || parsed.data.issuer !== this.issuer)
+            throw new Error('Stored login is invalid. Run permute auth login again.');
+        return parsed.data;
+    }
+    async write(value) {
+        await (await this.entry()).setPassword(JSON.stringify(value));
+    }
+    async remove() {
+        const entry = await this.entry();
+        if (await entry.getPassword())
+            await entry.deletePassword();
+    }
+    async exclusive(run) {
+        const directory = join(homedir(), '.config', 'permute', 'auth');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const lock = join(directory, `${this.account}.lock`);
+        const deadline = Date.now() + 30_000;
+        while (true) {
+            const acquired = await mkdir(lock, { mode: 0o700 }).then(() => true, (error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                return false;
+            });
+            if (acquired)
+                break;
+            if (Date.now() >= deadline)
+                throw new Error(`Another process is updating this login. Retry after it finishes. If a process crashed, stop other Permute CLI processes before removing ${lock}.`);
+            await setTimeout(100);
+        }
+        try {
+            return await run();
+        }
+        finally {
+            await rm(lock, { recursive: true, force: true });
+        }
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export * from './auth/oauth.js';

package/dist/auth.js

@@ -0,0 +1 @@
+export * from './auth/oauth.js';

package/dist/bridge.d.ts

@@ -0,0 +1,10 @@
+import { PermuteClient } from './client.js';
+import type { PublicApiOperationId } from './generated/runtime-contract.js';
+/** Executes the SDK itself behind a JSON RPC boundary; it does not implement API operations. */
+export declare class PermuteSdkBridge {
+    private readonly client;
+    constructor(client: PermuteClient);
+    supports(method: string, acceptsOperation?: (operationId: PublicApiOperationId) => boolean): boolean;
+    invoke(method: string, args: unknown[]): Promise<unknown>;
+    private resolve;
+}

package/dist/bridge.js

@@ -0,0 +1,62 @@
+import { PermuteDataset, PermuteFileDataset } from './client.js';
+import { SdkMethodFactory } from './method.js';
+const safeName = (name) => /^[A-Za-z][A-Za-z0-9_]*$/.test(name) && !['constructor', 'prototype', '__proto__'].includes(name);
+function decode(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(decode);
+    const item = value;
+    if (Object.keys(item).length === 1 && Array.isArray(item.__permuteSdkBytes)) {
+        if (!item.__permuteSdkBytes.every((byte) => typeof byte === 'number' && Number.isInteger(byte) && byte >= 0 && byte <= 255))
+            throw new Error('Invalid SDK byte data.');
+        return new Uint8Array(item.__permuteSdkBytes);
+    }
+    return Object.fromEntries(Object.entries(item).map(([key, child]) => [key, decode(child)]));
+}
+/** Executes the SDK itself behind a JSON RPC boundary; it does not implement API operations. */
+export class PermuteSdkBridge {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    supports(method, acceptsOperation) {
+        const selected = this.resolve(method);
+        if (!selected)
+            return false;
+        const operations = SdkMethodFactory.operationsFor(selected.fn);
+        return !!operations?.length && (!acceptsOperation || operations.every(acceptsOperation));
+    }
+    async invoke(method, args) {
+        const selected = this.resolve(method);
+        if (!selected)
+            throw new Error(`Unsupported SDK method: ${method}`);
+        const value = await Reflect.apply(selected.fn, selected.owner, args.map(decode));
+        // Resource helpers contain callbacks. Their public data is the portable result of an RPC.
+        const data = value instanceof PermuteDataset || value instanceof PermuteFileDataset ? value.data : value;
+        return JSON.parse(JSON.stringify(data ?? null));
+    }
+    resolve(method) {
+        const names = method.split('.');
+        if (names.some((name) => !safeName(name)) || names.length > 2)
+            return null;
+        const client = this.client;
+        if (names.length === 1) {
+            const name = names[0];
+            const fn = client[name];
+            return typeof fn === 'function' && SdkMethodFactory.operationsFor(fn)
+                ? { owner: this.client, fn: fn }
+                : null;
+        }
+        const namespace = client[names[0]];
+        if (!Object.hasOwn(client, names[0]) ||
+            !namespace ||
+            typeof namespace !== 'object' ||
+            !Object.hasOwn(namespace, names[1]))
+            return null;
+        const fn = namespace[names[1]];
+        return typeof fn === 'function' && SdkMethodFactory.operationsFor(fn)
+            ? { owner: namespace, fn: fn }
+            : null;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(args?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { OAuthLogin } from './auth.js';
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'linux' ? 'xdg-open' : undefined;
+    if (!command)
+        return;
+    const child = spawn(command, [url], { stdio: 'ignore' });
+    child.on('error', () => {
+        /* The printed link also works when no local browser is available. */
+    });
+    child.unref();
+}
+async function browserLogin(login, open) {
+    let destination;
+    let resolveCallback;
+    let rejectCallback;
+    const callback = new Promise((resolve, reject) => {
+        resolveCallback = resolve;
+        rejectCallback = reject;
+    });
+    const server = createServer((request, response) => {
+        if (!destination ||
+            request.method !== 'GET' ||
+            request.headers.host !== new URL(destination.redirectURI).host ||
+            !request.url?.startsWith('/callback?')) {
+            response.writeHead(400).end('This callback does not match the login request.');
+            return;
+        }
+        const url = new URL(request.url, destination.redirectURI);
+        if (url.searchParams.get('state') !== destination.state) {
+            response.writeHead(400).end('This callback does not match the login request.');
+            return;
+        }
+        response
+            .writeHead(200, {
+            'Content-Type': 'text/plain',
+            'Cache-Control': 'no-store',
+            'Content-Security-Policy': "default-src 'none'",
+        })
+            .end('Return to your terminal to finish connecting. You can close this tab.');
+        resolveCallback(url);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Could not open a loopback callback');
+    destination = login.beginBrowser(`http://127.0.0.1:${address.port}/callback`);
+    const timeout = setTimeout(() => rejectCallback(new Error('Login timed out. Start login again.')), 600_000);
+    const cancel = () => rejectCallback(new Error('Login canceled.'));
+    process.once('SIGINT', cancel);
+    try {
+        console.log(`Open this link to connect Permute CLI:\n${destination.url}`);
+        if (open)
+            openBrowser(destination.url);
+        return await login.finishBrowser(destination, await callback);
+    }
+    finally {
+        clearTimeout(timeout);
+        process.off('SIGINT', cancel);
+        server.closeAllConnections();
+        server.close();
+    }
+}
+export async function runCli(args = process.argv.slice(2)) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            issuer: { type: 'string' },
+            'api-url': { type: 'string' },
+            'device-code': { type: 'boolean' },
+            'no-browser': { type: 'boolean' },
+            help: { type: 'boolean' },
+        },
+    });
+    const [area, command] = positionals;
+    if (values.help || area !== 'auth' || !['login', 'logout', 'status'].includes(command ?? '')) {
+        console.log('permute auth login [--device-code] [--no-browser]\npermute auth status\npermute auth logout\n\nUse --issuer and --api-url together for a development environment.');
+        if (!values.help)
+            process.exitCode = 1;
+        return;
+    }
+    if (!!values.issuer !== !!values['api-url'])
+        throw new Error('Provide both --issuer and --api-url for another environment.');
+    const login = new OAuthLogin({ issuer: values.issuer, apiUrl: values['api-url'] });
+    if (command === 'logout') {
+        await login.logout();
+        console.log('CLI login revoked and removed from this device.');
+        return;
+    }
+    if (command === 'status') {
+        const credentials = await login.credentials();
+        console.log(`Connected to ${credentials.apiUrl}\nOrganization: ${credentials.organizationId ?? 'Not specified'}\nWorkspace: ${credentials.workspaceId ?? 'All accessible workspaces in this organization'}`);
+        return;
+    }
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    try {
+        if (values['device-code']) {
+            const request = await login.beginDevice();
+            console.log(`Open this link on any device:\n${request.url}\n\nConfirm this code: ${request.userCode}\nWaiting for your approval…`);
+            if (!values['no-browser'])
+                openBrowser(request.url);
+            await login.finishDevice(request, controller.signal);
+        }
+        else
+            await browserLogin(login, !values['no-browser']);
+        console.log('Connected. Credentials are saved in your operating system’s credential store.');
+    }
+    finally {
+        process.off('SIGINT', cancel);
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href)
+    runCli().catch(() => {
+        console.error('Could not complete authentication. Ensure your OS credential store is available, then retry. Use --device-code --no-browser to approve from another device.');
+        process.exitCode = 1;
+    });