insta 0.0.73 → 0.0.75

package/dist/agent.js

@@ -42,6 +42,8 @@ export async function saveAgentSession(session, cwd = process.cwd()) {
     await chmod(join(root, rel), 0o600);
 }
 export async function setupProjectAgentSession(api, projectId) {
+    if (api.agentCredential)
+        return false; // Nothing to enroll: the key itself is the agent identity.
     const id = projectId ?? (await readProject())?.projectId;
     if (!id)
         return false;
@@ -68,7 +70,8 @@ export async function loadAgentSession(apiUrl, projectId, cwd = process.cwd()) {
 // account-level paths in src/commands/.
 export const ACCOUNT_ROUTES = new Set(['agent', 'auth', 'me', 'orgs', 'regions', 'templates', 'tokens']);
 export async function agentHeaders(api, method, path, rawBody, scope = {}) {
-    if (!mode)
+    // A key minted by agent auth is already an agent principal on the platform and may not enroll a session.
+    if (!mode || api.agentCredential)
         return {};
     if (canonicalTarget(path) === '/agent/sessions' && method === 'POST')
         return {

package/dist/api.js

@@ -25,11 +25,15 @@ export class AgentApprovalRequired extends Error {
     }
 }
 // Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
-export function storeApiKeyCredential(cfg, token, user) {
+export function storeApiKeyCredential(cfg, token, user, agentCredential = false) {
     cfg.accessToken = token;
     delete cfg.refreshToken;
     if (user)
         cfg.user = user;
+    if (agentCredential)
+        cfg.agentCredential = true;
+    else
+        delete cfg.agentCredential;
 }
 export class ApiClient {
     cfg;
@@ -48,15 +52,18 @@ export class ApiClient {
         this.cfg.refreshToken = tokens.refreshToken;
         if (user)
             this.cfg.user = user;
+        delete this.cfg.agentCredential;
     }
     // Adopt a durable insta_ key as the credential (non-interactive `login --api-key`).
-    setApiKey(token, user) {
-        storeApiKeyCredential(this.cfg, token, user);
+    setApiKey(token, user, agentCredential) {
+        storeApiKeyCredential(this.cfg, token, user, agentCredential);
     }
+    get agentCredential() { return this.cfg.agentCredential === true; }
     clearSession() {
         delete this.cfg.accessToken;
         delete this.cfg.refreshToken;
         delete this.cfg.user;
+        delete this.cfg.agentCredential;
     }
     // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
     async request(method, path, body, opts = {}) {
@@ -86,7 +93,7 @@ export class ApiClient {
         const headers = { 'Content-Type': 'application/json', 'Insta-Hints': '1', 'User-Agent': USER_AGENT };
         if (auth && this.cfg.accessToken)
             headers.Authorization = `Bearer ${this.cfg.accessToken}`;
-        if (auth)
+        if (auth && scope.evidence !== false)
             Object.assign(headers, await agentHeaders(this, method, path, body === undefined ? '' : JSON.stringify(body), scope));
         const res = await this.fetchImpl(this.apiUrl + path, {
             method,

package/dist/commands/agent-policy.js

@@ -1,10 +1,21 @@
 import { ApiClient, requireProject } from '../api.js';
 import { handleApproval, info, printJson } from '../util.js';
-async function current() {
-    const api = await ApiClient.load();
-    const project = await requireProject();
+const PRESETS = ['full_access', 'read_only', 'branch_specific'];
+const DECISIONS = ['allow', 'deny', 'approve'];
+async function current(deps) {
+    const api = deps?.api ?? await ApiClient.load();
+    const project = deps?.project ?? await requireProject();
     const path = `/projects/${project.projectId}/agent-policy`;
     const out = await api.request('GET', path);
+    // `branchDeveloperRules` is a deprecated mirror of `rules`, kept in the response so that a CLI
+    // predating the rename can still edit it in place. Platform takes the legacy field over `rules`
+    // when a body carries both -- exactly so that old CLI's edit is not dropped -- so echoing the
+    // mirror back would silently discard everything this version writes. Only where Platform speaks
+    // the new contract, though: `actionCatalog` is how it announces that, and without one the mirror
+    // is the only rule set that exists, so dropping it would erase the project's overrides on the
+    // next PUT -- from `rule set`, but also from a `protect-branch` that never mentions rules.
+    if (out.policy && out.actionCatalog)
+        delete out.policy.branchDeveloperRules;
     return { api, project, path, policy: out.policy, out };
 }
 export function displayPolicy(out, opts, output = { info, printJson }) {
@@ -12,7 +23,9 @@ export function displayPolicy(out, opts, output = { info, printJson }) {
     const { policy, agentSessionEpoch } = out;
     if (opts.json)
         return printJson(out);
-    info(`agent policy: ${policy.mode}\nprotected branches: ${policy.protectedBranchIds.join(', ') || '(none)'}\nsession epoch: ${agentSessionEpoch}`);
+    const overrides = Object.keys(policy.rules ?? policy.branchDeveloperRules ?? {}).length;
+    info(`agent policy: ${policy.mode}${overrides ? ` (${overrides} rule${overrides === 1 ? '' : 's'})` : ''}`
+        + `\nprotected branches: ${policy.protectedBranchIds.join(', ') || '(none)'}\nsession epoch: ${agentSessionEpoch}`);
     if (out.effectiveRules) {
         for (const [scope, rules] of Object.entries(out.effectiveRules)) {
             info(`\n${scope}:`);
@@ -31,35 +44,122 @@ export async function get(opts) {
     // Forward the public response, never the internal API client (which holds credentials).
     displayPolicy(out, opts);
 }
-async function update(change, opts) {
-    const state = await current();
-    await change(state.policy, state);
-    const result = await state.api.rawRequest('PUT', state.path, state.policy);
+/**
+ * The decisions that moved but were NOT asked for. Switching off `full_access` is the case that
+ * needs this: the fixed invariants (project.delete, agent_policy.update, …) stop being allowed and
+ * protected branches begin to apply, so a one-rule edit can move a dozen decisions. Diffed from
+ * Platform's own resolved view before and after, never re-derived here — the same reason this CLI
+ * does not evaluate a policy locally.
+ */
+export function sideEffects(before, after, asked) {
+    const from = before.effectiveRules, to = after.effectiveRules;
+    if (!from || !to)
+        return [];
+    const lines = [];
+    for (const scope of Object.keys(to)) {
+        for (const [action, decision] of Object.entries(to[scope])) {
+            // The named action is suppressed only in the context the rule governs. That same action
+            // moving in another context is a consequence of the mode change, not the edit that was asked
+            // for — `rule set deploy deny` off full_access also starts denying deploy on protected
+            // branches, and that is precisely what the caller needs told.
+            if ((scope === 'unprotectedBranch' && asked.includes(action)) || from[scope]?.[action] === decision)
+                continue;
+            lines.push(`  ${scope}.${action}: ${from[scope]?.[action] ?? '(unknown)'} -> ${decision}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The policy a `rule set` should PUT. Exported because the interesting part is not the request:
+ * leaving a preset has to snapshot every decision it was already making, or setting one rule
+ * silently rewrites all the others to whatever the new mode's defaults happen to be.
+ */
+export function applyRule(policy, out, action, decision) {
+    const catalog = out.actionCatalog;
+    // A Platform predating the rename has neither a catalog nor a `rules` field, and reads only the
+    // old one. Nothing below applies there.
+    if (!catalog)
+        return { ...policy, branchDeveloperRules: { ...(policy.branchDeveloperRules ?? {}), [action]: decision } };
+    const entry = catalog.find(e => e.action === action);
+    if (!entry)
+        throw new Error(`unknown action: ${action}\nrun: insta agent-policy get --json`);
+    if (!entry.editable)
+        throw new Error(`${action} is a fixed policy invariant and cannot be overridden`);
+    // Snapshot taken from the resolved unprotected-branch view, which is the context these rules
+    // apply to; protected branches stay a separate, fixed denial.
+    const base = policy.mode === 'customize'
+        ? policy.rules
+        : Object.fromEntries(catalog.filter(e => e.editable).map(e => [e.action, out.effectiveRules.unprotectedBranch[e.action]]));
+    return { ...policy, mode: 'customize', rules: { ...base, [action]: decision } };
+}
+/** `change` either mutates the policy in place or returns the replacement. */
+// `asked` opts into the side-effect report and names the actions the caller chose. Only `rule set`
+// passes it: a mode change is expected to move everything, so listing the whole table is noise.
+async function update(change, opts, asked, deps) {
+    const state = await current(deps);
+    const next = (await change(state.policy, state)) ?? state.policy;
+    const result = await state.api.rawRequest('PUT', state.path, next);
     if (handleApproval(result, opts.json))
         return;
+    // Printing does not end the command: the side-effect report below is owed to `--json` too, since
+    // a scripted caller is the one least able to notice for itself that leaving a preset moved
+    // decisions it never named. The report is on stderr, so stdout stays a parseable document.
     if (opts.json)
-        return printJson(result.body);
-    info(`agent policy updated: ${result.body.policy.mode}`);
+        printJson(result.body);
+    else
+        info(`agent policy updated: ${result.body.policy.mode}`);
+    if (!asked)
+        return;
+    // The PUT already landed. A failed diagnostic GET costs the comparison, not the update: rejecting
+    // here would report a mutation that happened as a failure, and invite a retry of a done edit.
+    let after;
+    try {
+        after = await state.api.request('GET', state.path);
+    }
+    catch {
+        process.stderr.write('note: could not determine whether this changed decisions you did not name\n');
+        return;
+    }
+    const moved = sideEffects(state.out, after, asked);
+    if (moved.length)
+        process.stderr.write(`note: this also changed decisions you did not name:\n${moved.join('\n')}\n`);
 }
-export async function set(mode, opts) {
+export async function set(mode, opts, deps) {
     const normalized = mode.replace(/-/g, '_');
-    if (!['full_access', 'read_only', 'branch_developer'].includes(normalized))
-        throw new Error('mode must be full-access, read-only, or branch-developer');
-    return update(policy => { policy.mode = normalized; }, opts);
+    // `branch_developer` is the pre-rename name for `branch_specific`, still accepted here so a
+    // script written against the old CLI keeps working. `customize` is deliberately NOT settable:
+    // it means "carrying overrides", which is what `agent-policy rule set` produces.
+    const resolved = normalized === 'branch_developer' ? 'branch_specific' : normalized;
+    if (!PRESETS.includes(resolved))
+        throw new Error('mode must be full-access, read-only, or branch-specific');
+    // A preset carries no rules; Platform refuses one that does. Which field carries "no rules"
+    // depends on the same capability check `applyRule` makes: without an `actionCatalog` Platform
+    // predates the rename, so it only knows the old mode name and only reads the old rule field —
+    // clearing `rules` there would leave every override standing under the new mode.
+    return update((policy, { out }) => {
+        if (out.actionCatalog) {
+            policy.mode = resolved;
+            policy.rules = {};
+        }
+        else {
+            policy.mode = resolved === 'branch_specific' ? 'branch_developer' : resolved;
+            policy.branchDeveloperRules = {};
+        }
+    }, opts, undefined, deps);
 }
-export async function protect(branch, enabled, opts) {
+export async function protect(branch, enabled, opts, deps) {
     return update(async (policy, { api, project }) => {
         const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`);
         const found = branches.find((b) => b.id === branch || b.name === branch);
         if (!found)
             throw new Error('branch not found');
         policy.protectedBranchIds = enabled ? [...new Set([...policy.protectedBranchIds, found.id])] : policy.protectedBranchIds.filter((id) => id !== found.id);
-    }, opts);
+    }, opts, undefined, deps);
 }
-export async function rule(action, decision, opts) {
-    if (!['allow', 'deny', 'approve'].includes(decision))
+export async function rule(action, decision, opts, deps) {
+    if (!DECISIONS.includes(decision))
         throw new Error('decision must be allow, deny, or approve');
-    return update(policy => { policy.branchDeveloperRules[action] = decision; }, opts);
+    return update((policy, { out }) => applyRule(policy, out, action, decision), opts, [action], deps);
 }
 export async function revoke(opts) {
     const api = await ApiClient.load();

package/dist/commands/auth.js

@@ -1,6 +1,7 @@
 import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { ApiClient, ApiError, linkedProject } from '../api.js';
+import { agentMode } from '../agent.js';
 import { ENVS, ENV_NAMES, envForApiUrl, isEnvName } from '../env.js';
 import { info, die, printJson, promptPassword, openUrl } from '../util.js';
 /** --api-url and --env both set the target host; --api-url wins (more specific), matching the
@@ -16,15 +17,23 @@ function targetApiUrl(opts) {
         die(`unknown --env "${opts.env}" — expected one of: ${ENV_NAMES.join(', ')}`);
     return ENVS[want].api;
 }
-// `device` is injectable so the dispatch itself is testable (repo pattern: DI fakes, no mocks).
-export async function login(opts, device = loginDevice) {
+// `device`/`claim` are injectable so the dispatch itself is testable (repo pattern: DI fakes, no mocks).
+export async function login(opts, device = loginDevice, claim = loginClaim) {
     // Login modes are exclusive — pick one. Check presence (not truthiness) so an explicit
     // empty --api-key= is rejected by validation rather than silently falling through.
     if (opts.apiKey !== undefined) {
-        if (opts.device || opts.oauth || opts.email)
-            die('choose one login mode: --api-key, --device, --oauth, or --email');
+        if (opts.device || opts.oauth !== undefined || opts.email !== undefined || opts.claim !== undefined || opts.password !== undefined || process.env.INSTA_PASSWORD !== undefined)
+            die('choose one login mode: --api-key, --claim, --device, --oauth, or --email');
         return loginApiKey(opts.apiKey, opts);
     }
+    if (opts.claim !== undefined) {
+        if (opts.device || opts.oauth !== undefined || opts.email !== undefined || opts.password !== undefined || process.env.INSTA_PASSWORD !== undefined)
+            die('choose one login mode: --api-key, --claim, --device, --oauth, or --email (a password belongs to --email)');
+        if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(opts.claim))
+            die('--claim needs an email address: the account that will authorize this agent');
+        // The human types the code on the console; open it here only when a browser is on this machine.
+        return claim(opts.claim, opts, agentMode() ? undefined : openUrl);
+    }
     if (opts.device)
         return device(opts);
     if (opts.oauth)
@@ -83,6 +92,19 @@ export async function loginDevice(opts, open) {
     await api.persist();
     info(`logged in as ${me.user.email ?? me.user.id} @ ${api.apiUrl}`);
 }
+// `insta login --claim <email>`: the auth.md user claimed flow. The named user confirms a code on
+// the console, the platform mints an insta_ key, and it is stored exactly as --api-key stores one.
+export async function loginClaim(email, opts, open, grant = claimGrant) {
+    const api = await ApiClient.load();
+    const target = targetApiUrl(opts);
+    if (target)
+        api.setApiUrl(target);
+    const client = agentMode()?.client ?? 'unknown';
+    const key = await grant(email, client, (path, body, signal) => api.request('POST', path, body, { auth: false, signal }), sleepSeconds, open);
+    const user = await applyApiKeyLogin(api, key);
+    await api.persist();
+    info(`logged in as ${user.email ?? user.id} @ ${api.apiUrl}`);
+}
 // Non-interactive login with a durable insta_ key (minted via POST /tokens): store it and confirm against /me. No browser, no polling.
 export async function loginApiKey(key, opts) {
     const api = await ApiClient.load();
@@ -93,7 +115,7 @@ export async function loginApiKey(key, opts) {
     await api.persist();
     info(`logged in as ${user.email ?? user.id} @ ${api.apiUrl}`);
 }
-// Verify an insta_ key and store it: set it first so the /me probe is authed with the key itself, then re-store with the resolved user (401 → bad/revoked).
+// Verify an insta_ key with a bare /me probe (an agent-minted key cannot enroll a session, and /me says which kind this is), then store it with the user and that kind.
 export async function applyApiKeyLogin(client, key) {
     key = key.trim(); // tolerate a trailing newline / stray whitespace from `--api-key "$(cat token)"`
     if (!key.startsWith('insta_'))
@@ -101,7 +123,7 @@ export async function applyApiKeyLogin(client, key) {
     client.setApiKey(key);
     let me;
     try {
-        me = await client.request('GET', '/me');
+        me = await client.request('GET', '/me', undefined, { evidence: false });
     }
     catch (e) {
         if (e instanceof ApiError && e.status === 401)
@@ -110,7 +132,7 @@ export async function applyApiKeyLogin(client, key) {
     }
     if (!me?.user)
         throw new Error('unexpected response while verifying the API key');
-    client.setApiKey(key, me.user);
+    client.setApiKey(key, me.user, me.agentCredential === true);
     return me.user;
 }
 const sleepSeconds = (s) => new Promise((r) => setTimeout(r, s * 1000));
@@ -192,6 +214,92 @@ export async function deviceGrant(post, wait = sleepSeconds, open) {
     }
     throw new Error(`device login expired before it was approved — run \`insta login${open ? '' : ' --device'}\` again`);
 }
+// auth.md user claimed flow (service_auth). The agent knows the user's email; InstaCloud gives a
+// 6-digit code and a console link; only a session for that email can type the code. We poll the
+// standard token endpoint with the WorkOS claim grant and get an insta_ key back. Poster + wait
+// are injected like deviceGrant's. JSON bodies: the platform's token route accepts them.
+const CLAIM_GRANT = 'urn:workos:agent-auth:grant-type:claim';
+// A poll interval is seconds, from the server: clamp it so a silly value cannot become a ~1 ms timer.
+const pollInterval = (value, fallback) => {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.min(Math.max(n, 1), 3600) : fallback;
+};
+export async function claimGrant(email, client, post, wait = sleepSeconds, open, now = Date.now) {
+    const start = (await post('/agent/auth', { type: 'service_auth', login_hint: email, client }));
+    if (!start?.claim_token || !start.claim?.user_code || !start.claim.verification_uri) {
+        throw new Error('malformed registration response (missing claim) — is the platform up to date?');
+    }
+    const expiresAt = Date.parse(start.claim_token_expires);
+    const deadline = Math.min(Number.isFinite(expiresAt) ? expiresAt : Infinity, now() + 86_400_000);
+    const show = (block, fresh) => {
+        if (fresh)
+            info('the code expired — here is a new one.');
+        if (open) {
+            info('opening your browser…');
+            open(block.verification_uri);
+        }
+        info(`to authorize this agent, open this link, sign in as ${email}, and enter this code: ${block.user_code}`);
+        info(`  ${block.verification_uri}`);
+    };
+    show(start.claim, false);
+    info(`waiting for ${email} to confirm… (ctrl-c to abort)`);
+    let interval = pollInterval(start.claim.interval, 5);
+    let reminted = false;
+    const expired = () => new Error(`the request expired before ${email} confirmed it — run \`insta login --claim ${email}\` again`);
+    while (now() < deadline) {
+        await wait(interval);
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw expired();
+        const signal = AbortSignal.timeout(Math.ceil(Math.min(remaining, 30_000)));
+        let grant = null;
+        try {
+            grant = (await post('/api/auth/oauth2/token', { grant_type: CLAIM_GRANT, claim_token: start.claim_token }, signal));
+        }
+        catch (e) {
+            if (e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError')) {
+                if (now() >= deadline)
+                    throw expired();
+                continue;
+            }
+            if (!(e instanceof ApiError))
+                continue; // transport blip — keep polling until the deadline
+            const code = e.message;
+            if (code === 'authorization_pending')
+                continue;
+            if (code === 'slow_down' || e.status === 429) {
+                interval = Math.min(interval + 5, 3600);
+                continue;
+            }
+            if (code === 'expired_token') {
+                if (reminted)
+                    throw expired();
+                let again;
+                try {
+                    again = (await post('/agent/auth/claim', { claim_token: start.claim_token, email }, signal));
+                }
+                catch (re) {
+                    if (re instanceof ApiError && re.message === 'claim_expired')
+                        throw expired();
+                    if (!(re instanceof ApiError))
+                        continue; // re-mint timeout or transport blip: the next expired_token asks again
+                    throw re;
+                }
+                reminted = true;
+                if (!again?.claim_attempt?.user_code || !again.claim_attempt.verification_uri)
+                    throw new Error('malformed claim response (missing claim_attempt)');
+                interval = pollInterval(again.claim_attempt.interval, interval);
+                show(again.claim_attempt, true);
+                continue;
+            }
+            throw e; // invalid_grant and friends: not retryable
+        }
+        if (!grant?.access_token)
+            throw new Error('malformed token response (missing access_token)');
+        return grant.access_token;
+    }
+    throw expired();
+}
 // Start a loopback server, open the browser at the platform bridge, and await the token.
 function browserOauth(apiUrl, provider) {
     return new Promise((resolve, reject) => {