@permute/sdk 0.7.0 → 0.8.1

package/README.md

@@ -6,6 +6,36 @@ The SDK supports Node.js 20 and newer and includes TypeScript declarations.
 
 See the [changelog](https://permute.ai/docs/changelog) for release notes and upgrade guidance.
 
+## Sign in without an API key
+
+The CLI ships with `@permute/sdk`. Run it with `bunx`:
+
+```sh
+bunx @permute/sdk auth login
+# Or approve from another computer:
+bunx @permute/sdk auth login --device-code --no-browser
+bunx @permute/sdk auth status
+bunx @permute/sdk auth logout
+```
+
+Choose an organization, optionally limit the connection to one workspace, then select resources and permissions to approve in Permute. The CLI stores renewable credentials in your operating system’s credential store (no plaintext fallback). Active logins have no fixed maximum lifetime and expire after 30 days without renewal; company sign-in rules can require earlier authentication. Logging out revokes access before removing the local credential. Signing in again revokes the previous stored CLI session.
+
+The SDK reuses credentials in memory between requests and reloads the OS store before renewal or when another process changes the saved login. The local auth directory holds only a lock and a non-secret change marker; tokens stay out of ordinary files. Current server permissions and revocation still apply to every request.
+
+The CLI prints the issuer and `permute-cli` entry name to stderr before accessing the OS store. macOS controls its own permission dialog, which may identify the Node or Bun process. SDK applications stay silent by default and can supply `onCredentialStoreAccess: (issuer) => { /* show a notice */ }` to `OAuthLogin`; the callback runs once before the default OS store is accessed and receives no credentials.
+
+```ts
+import { OAuthLogin } from '@permute/sdk/auth';
+
+const client = await new OAuthLogin().client();
+const workspace = client.withWorkspace('wksp_...');
+const apps = await workspace.apps.list();
+```
+
+The client renews access automatically. Existing permissions still control data, drafting, publication and action execution. Each request must fit both the approved selection and your current permissions. For organization-wide logins, use `client.withWorkspace(id)` for workspace API calls. Local stdio MCP can reuse this saved login when no API key is configured. Hosted app and hosted MCP credentials stay bound to their own audiences. API-key clients continue to work with `new PermuteClient({ apiKey })`.
+
+For a development environment, pass both `--issuer https://auth.example.test` and `--api-url https://api.example.test` to CLI commands, or the matching `issuer` and `apiUrl` to `OAuthLogin`. Only HTTPS origins and local loopback HTTP are accepted. Use the same environment for login and logout.
+
 ## Dashboard source authoring
 
 API-key clients with dashboard write access can read and replace the complete
@@ -96,10 +126,12 @@ replacement without checking the changes. Graph commands use `get`’s numeric f
 Publishing requires a successful run of the current flow version. Deleting a flow
 requires admin access; its owned operations are deleted with it.
 
-Data Flow and operation authoring are REST/SDK only. MCP serves end users reading
-and analyzing governed outputs; it does not expose code editing, draft inspection,
-execution, or publication. Hosted connectors also restrict access to selected sources. Flow scheduling and standalone operation
-creation are not part of this surface.
+Data Flow and operation authoring are REST/SDK only. MCP does not expose their code
+editing, draft inspection, execution, or publication. Hosted MCP access uses
+selected sources or a hosted app's current grants and published action bindings,
+intersected with the user's permissions. App actions require confirmation in
+Permute; see the [MCP guide](https://permute.ai/docs/mcp). Flow scheduling and
+standalone operation creation are not part of this surface.
 
 ## Publish write syncs
 
@@ -379,6 +411,14 @@ query (materialized connector fields come from the stored SQL table). Warehouse
 sources use DuckDB SQL and can be queried together. Live remote sources use
 their native SQL dialect and must be queried one at a time.
 
+Warehouse SQL queries accept up to **20 distinct sources per query**. The shared
+[`WAREHOUSE_QUERY_SOURCE_LIMIT`](../core/src/constants/queryLimits.ts) keeps the
+SQL executor, natural-language query sessions, and UI source picker consistent.
+This cap bounds the number of sources prepared for a query (each source can
+contain many tables); it does not limit workspace connections or change access
+permissions. Select only the sources needed. Requests above the cap are rejected
+before source loading.
+
 ```ts
 const dataset = sources.items.find((source) => source.type === 'dataset');
 if (!dataset) throw new Error('No dataset is available');
@@ -424,6 +464,14 @@ handling).
 
 ## Error Handling
 
+App and Business Action authorization failures can return `permission_denied` with
+`error.details` containing `operation`, `requiredLevel` (`read`, `write`, or `admin`),
+and `reason`. Reasons are `caller_permission_required`, `application_grant_required`,
+`source_delegation_required`, or `declared_capability_required`. Both SDK entries
+preserve these fields on `PermuteApiError.details`. Details are optional: unreadable,
+missing, and foreign resources return the same opaque 404, so a caller cannot use
+denials to discover private resources. See [authentication](https://permute.ai/docs/authentication#authorization-errors).
+
 ```ts
 import { PermuteApiError } from '@permute/sdk';
 
@@ -589,14 +637,21 @@ directly; invoking any bound action requires viewer confirmation.
 
 Source reads require whole-resource read permission for both the app and viewer,
 including databases, datasets, connectors, and operation outputs. Table, row,
-and column grants are unsupported; subResourceId is available only to revoke an
-existing scoped grant. Test source discovery and
-a bounded query as the intended viewer before testing the assistant; an empty
+and column grants within a shared source are unsupported; subResourceId is available
+only to revoke an existing scoped grant. Role-based reads can use separate filtered
+Data Table or Data Flow outputs shared with the appropriate viewers and apps while
+broader upstream sources stay restricted. Follow the
+[filtered-output guide](https://permute.ai/docs/guides/deploy-app#app-filtered-views)
+for allowed rows/columns, historical access, and refresh after assignment changes.
+Test source discovery and a bounded query as the intended viewer before testing the assistant; an empty
 source list describes that viewer's app access, not the workspace's contents.
 
 Plan app and viewer permissions separately. Use `client.apps.setGrant()` for exact
 approved app source IDs; an administrator uses Permute sharing for viewer app and
-source access. The public SDK has no general user-permission mutation methods.
+source access. Authorized management clients can also use `client.permissions.list`,
+`create`, `update`, `delete`, and `inspect`; hosted app, delegated action, MCP, and
+connector sessions cannot manage grants. The management key needs its own access
+and delegation authority.
 Inspect the complete source before approval (a database may contain other apps’
 tables); never widen a rejected table grant automatically. Apps and keys do not
 inherit their creators’ access. The public
@@ -664,6 +719,15 @@ operation only after resolving any earlier uncertain write.
 
 ## Business actions
 
+Handlers can read declared managed database tables with
+`db.read({ sourceId, table, where, limit })`. Use trusted `caller: { id, type }`
+to choose permitted rows, return only approved fields, and grant invocation access
+without granting database Read. Declare the published schema revision and
+`readTables` in the action's source binding (`writeTables: []` for read-only use).
+Caller identity does not include membership roles; application-specific team rules
+can use a server-side roster. See the
+[caller-filtered database read example](https://permute.ai/docs/guides/business-actions#action-database-reads).
+
 Action handlers can receive a declared `platform` SDK facade. Add `platform.methods`
 and `platform.permissions` to the definition, then call
 `platform.withStep('upload').datasets.create({ type: 'file', fileName: input.fileName, contentType: input.contentType, sizeBytes: input.sizeBytes })`.
@@ -671,8 +735,9 @@ Without `data`, the call returns dataset metadata and an upload target; the hand
 can return that target for the browser to upload bytes. Providing `data` also
 uploads bytes inside the action and must fit its execution and payload limits.
 The server runs the real SDK using the action's delegated grants (callers need
-only action invocation permission). Saving and publishing require resource admin
-authority. Every SDK call needs a distinct, deterministic step ID, including reads.
+only action invocation permission). Saving requires Edit draft on the action and
+Read on declared resources; publishing requires Publish and resource Admin to
+delegate those capabilities. Every SDK call needs a distinct, deterministic step ID, including reads.
 Completed calls replay their saved results; reusing an ID with a different method
 or arguments returns `request_conflict`. Calls with uncertain outcomes return
 `outcome_unknown` and block automatic resend. Earlier SDK effects aren't rolled
@@ -681,14 +746,63 @@ Calls share action time and payload limits; dataset helpers return plain data.
 See the [business-actions guide](https://permute.ai/docs/guides/business-actions)
 for supported methods, limits, and authoring examples.
 
+For hosted browser uploads, send file metadata through the bound action and return
+`{ datasetId: dataset.id, upload: dataset.upload }` in its declared output contract.
+Send the `File` as the raw body of `fetch(upload.url, { method: upload.method,
+headers: upload.headers, body: file, credentials: 'omit', redirect: 'error' })`.
+Keep every returned header (including `If-None-Match: *`); don't wrap bytes in
+`FormData` or send cookies or API keys to S3. File bytes bypass the action's
+100 KB input limit. Compiled signed-in apps permit connections to the stage's exact
+regional Datasets bucket; its CORS rule supports PUT and the returned headers,
+including from custom app domains.
+
+S3 object-created events start normal dataset processing. Use a separately bound
+status action declaring `datasets.get` to poll with a new invocation request ID
+for each fresh read; enforce any caller-specific ownership rules in that action.
+Hosted app sessions cannot call dataset APIs directly. Upload URLs are bearer
+capabilities valid for up to 15 minutes (temporary AWS credentials can expire
+earlier), so don't persist or log them. Replaying the create action returns the
+original target without renewing its expiry. After an uncertain PUT, inspect
+processing status before requesting another dataset; a 412 means an object
+already occupies the signed key.
+
 Use `client.actions.create`, `definition`, and `saveDefinition` to author a typed
 handler with declared database, connector, or SDK capabilities. SDK-only and
 connector-only actions need no managed database. Publish with
 `client.revisions.publish`, then call `client.actions.invoke` with a stable
-`requestId` and input. `list` exposes published contracts; reading definitions
-requires admin permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
+`requestId` and input. `list` and `get` expose published contracts and declared capabilities; reading definitions
+requires View code permission. See the [business action guide](https://permute.ai/docs/guides/business-actions)
 for the complete create, save, publish, and invoke workflow.
 
+### Self-describing action contracts
+
+Use input/output schema descriptions to explain purpose, business terms,
+relationships, create/update behavior, consequential effects, and result meaning
+(external callers cannot inspect the handler). Declare known fields, enums,
+required/optional and nullable values, bounds, and typed outputs structurally.
+Keep field descriptions beside their fields and operation descriptions beside
+their alternatives. Reuse schema definitions for published contracts and handler
+validation where practical.
+
+Bounded `oneOf` alternatives support operation-specific inputs: give each
+alternative a required selector with a distinct `const` value. Exactly one must
+match. Limits are 32 alternatives per `oneOf`, 500 schema nodes, and depth 12.
+Regexes, references, formats, and other composition keywords remain unsupported.
+Keep authorization, normalization, formats, and live business-state checks in the handler.
+
+Supply input/output and field `examples`; save and publication validate them
+without executing the handler. Limits are 10 values per examples array and 50
+examples per input/output contract. Defaults are descriptive and are not inserted.
+Test the handler against examples, rejections, and conflicts as well: structural
+validation cannot guarantee a later write succeeds.
+
+`client.actions.list()` and `get()` return the current published contract, or
+`contract: null` before publication. App MCP discovery retains its app's permitted
+action bindings and exact revision pins. Draft changes do not update those views.
+Declared capabilities are bounds, not a preview of affected records. See the
+[contract-authoring guide](https://permute.ai/docs/guides/business-actions#action-contracts)
+for a complete schema example.
+
 Permute authenticates callers and checks the action’s required invocation
 permission. Hosted app calls also require app access, an app invocation grant,
 and the action revision pinned in the served release. Administrators approve
@@ -729,6 +843,10 @@ values up to 500). Invalid rejections and unexpected exceptions return a safe
 `execution_failed` response; exception text stays in server logs.
 
 Both SDK entries expose `PermuteApiError.code`, `.status`, and `.details`.
+Schema validation details include `path`, `rule`, and `schemaPath`, with bounded
+`allowedValues` or `constraint` where available. Compound errors can include
+`issues`; truncation flags indicate omitted diagnostics. Hosted MCP retains the
+same public error code and details in its error result.
 Branch on the code (not message text):
 
 | Code                             | HTTP     | Recovery                                                              |
@@ -749,7 +867,9 @@ does not establish that nothing happened; reconcile provider state first.
 ### Connector bindings
 
 An action definition can bind multiple connector accounts by name alongside its database
-schema bindings. Save and publish require admin permission on each selected resource.
+schema bindings. Saving requires Edit draft on the action and Read on each selected
+resource; publishing requires Publish on the action and source Admin to delegate
+the capabilities.
 The action runs with those delegated capabilities; callers need its invocation permission.
 
 ```ts
@@ -836,3 +956,13 @@ await client.apps.setAddress(app.id, {
 ```
 
 Set `address: null` with the currently observed URL to remove it. Stale edits and occupied names return 409. Each hostname uses its own app session; permissions and password-demo restrictions apply on every address. Namespace ownership management is restricted to signed-in organization admins, while these app-level methods support API keys with app admin permission.
+
+## Request missing access
+
+Use `client.accessRequests.create({ resourceId, level: 'read', reason: 'Need this app for customer support' })` to record a request for the authenticated caller. Recording a request does not grant access or confirm that the resource exists. List your requests with `client.accessRequests.list()`.
+
+Reviewers use `client.accessRequests.list({ view: 'review', state: 'pending' })`, then `client.accessRequests.decide(requestId, { decision: 'approved' })` to grant the requested caller access, verify effective access and close the request atomically. Approval never expands app grants (missing app access must be handled separately). Use `resolved` only to verify access already granted. Requesters can cancel with `{ decision: 'cancelled' }` (reviewers can reject with `{ decision: 'rejected' }`).
+
+Lists include a `total` count under the same authorization and filters as their rows. Use `{ view: 'mine', state: 'pending' }` for your pending requests and `{ view: 'history' }` for completed or expired requests you own or currently administer. Resource administrators can list across their authorized resources or narrow with `resourceId`. Expiry and visibility filters apply before cursor pagination.
+
+Hosted apps use `app.accessRequests.create/list/get/cancel`; the server derives app scope from the signed session. See the [access-request contract](../core/src/permissions/README.md) for expiry, reviewer authority and current limits.

package/dist/app.d.ts

@@ -1,3 +1,5 @@
+import type { AccessRequest, AccessRequestInput, AccessRequestList } from './types.js';
+export type { AccessRequest, AccessRequestInput, AccessRequestList } from './types.js';
 import type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail } from './types.js';
 export { PermuteApiError } from './errors.js';
 export type { ActionRequest, ActionReceipt, QueryRequest, QueryResponse, AppUser, ChatSendRequest, ChatDecisionRequest, ChatResponse, SourceList, SourceDetail, } from './types.js';
@@ -15,6 +17,12 @@ export declare class PermuteAppClient {
     private readonly revisionId;
     private readonly fetcher;
     constructor(options?: PermuteAppClientOptions);
+    readonly accessRequests: {
+        create: (body: AccessRequestInput, options?: AppRequestOptions) => Promise<AccessRequest>;
+        list: (cursor?: string, options?: AppRequestOptions) => Promise<AccessRequestList>;
+        get: (requestId: string, options?: AppRequestOptions) => Promise<AccessRequest>;
+        cancel: (requestId: string, options?: AppRequestOptions) => Promise<AccessRequest>;
+    };
     readonly actions: {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
         invoke: (actionId: string, request: ActionRequest, options?: AppRequestOptions) => Promise<ActionReceipt>;

package/dist/app.js

@@ -19,6 +19,12 @@ export class PermuteAppClient {
         this.revisionId = revision[1];
         this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
     }
+    accessRequests = {
+        create: (body, options) => this.request('access-requests', body, options),
+        list: (cursor, options) => this.request(`access-requests${cursor ? `?cursor=${encodeURIComponent(cursor)}` : ''}`, undefined, options),
+        get: (requestId, options) => this.request(`access-requests/${encodeURIComponent(requestId)}`, undefined, options),
+        cancel: (requestId, options) => this.request(`access-requests/${encodeURIComponent(requestId)}/decisions`, { decision: 'cancelled' }, options),
+    };
     actions = {
         /** Keep requestId and input unchanged when retrying an uncertain result. */
         invoke: (actionId, request, options) => this.request(`actions/${encodeURIComponent(actionId)}/invoke`, request, options),

package/dist/auth/oauth.d.ts

@@ -0,0 +1,66 @@
+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;
+    /** Called once before the default OS credential store is accessed; no tokens are passed. */
+    onCredentialStoreAccess?: (issuer: string) => void;
+}
+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 { TOKEN_REFRESH_BUFFER_MS, 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, options.onCredentialStoreAccess);
+        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, previous) {
+        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 existing = previous ?? (await this.store.read());
+            if (existing && existing.sessionId !== tokens.session_id)
+                await this.revoke(existing.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() + TOKEN_REFRESH_BUFFER_MS)
+                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, current);
+        });
+    }
+    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,47 @@
+import { z } from 'zod';
+export declare const TOKEN_REFRESH_BUFFER_MS = 60000;
+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>;
+}
+/** Credentials are cached in memory only; disk holds a lock and a non-secret change marker. */
+export declare class SystemCredentialStore implements CredentialStore {
+    private readonly issuer;
+    private readonly onAccess?;
+    private readonly account;
+    private readonly directory;
+    private readonly revisionPath;
+    private cached?;
+    private announced;
+    constructor(issuer: string, onAccess?: ((issuer: string) => void) | undefined);
+    private entry;
+    read(): Promise<{
+        issuer: string;
+        apiUrl: string;
+        workspaceId?: string | undefined;
+        organizationId?: string | undefined;
+        sessionId: string;
+        access: string;
+        refresh: string;
+        expiresAt: number;
+    } | null>;
+    private validate;
+    write(value: LoginCredentials): Promise<void>;
+    remove(): Promise<void>;
+    private markChanged;
+    exclusive<T>(run: () => Promise<T>): Promise<T>;
+}
+export {};