@north-light/sdk 0.3.479 → 0.3.481

package/README.md

@@ -18,7 +18,7 @@ It is a client, not a runtime. It never runs an agent itself, and it does not bu
 npx @north-light/sdk@latest init my-app
 ```
 
-`init` writes a runnable app, a signing key and the `northlight` Agent Skill for Claude Code, Codex, Cursor and Copilot, and prints the console steps. `npx @north-light/sdk skill` refreshes the skill after you change the pinned SDK version, and `npx @north-light/sdk env --client-id <client id>` writes the app's env file. None of them needs crtr.
+`init` writes a runnable app, a signing key and the `northlight` Agent Skill for Claude Code, Codex, Cursor and Copilot, and prints the next steps: `npx @north-light/sdk login` (you approve once in the browser), then `npx @north-light/sdk register`, which registers the app and writes its env file. `npx @north-light/sdk skill` refreshes the skill after you change the pinned SDK version. None of them needs crtr.
 
 ## Install
 

package/dist/apps-command.d.ts

@@ -0,0 +1,2 @@
+/** The `crouter-sdk apps <leaf>` command. Returns the process exit code. */
+export declare function runApps(argv: string[]): Promise<number>;

package/dist/apps-command.js

@@ -0,0 +1,119 @@
+import { usageOf } from './cli-usage.js';
+import { callLeaf } from './directory-client.js';
+import { envValueOf } from './env-command.js';
+import { NOT_LOGGED_IN, ENV_PATH, openSession, parseFlags, publicJwkFromFile, readProjectEnv, reportFailure, resolveIssuer } from './developer-common.js';
+const USAGE = usageOf('apps');
+const list = (...names) => names.map((name) => `--${name}`);
+/** The leaves a coding agent's login may call (the directory enforces it too; this table only picks the flags). */
+const LEAVES = {
+    'mine': { path: 'mine', app: false, flags: {} },
+    'get': { path: 'get', app: true, flags: {} },
+    'update': { path: 'update', app: true, flags: { value: list('name', 'origin', 'logo', 'justification') } },
+    'set-redirect-uris': { path: 'set-redirect-uris', app: true, flags: { list: list('redirect-uri') } },
+    'asks': { path: 'asks', app: true, flags: { value: list('group', 'source', 'query'), bool: list('requested') } },
+    'set-scopes': { path: 'set-scopes', app: true, flags: { list: list('scope', 'add', 'remove'), bool: list('clear') } },
+    'set-requires': { path: 'set-requires', app: true, flags: { list: list('provider', 'add', 'remove'), bool: list('clear') } },
+    'set-run-notice-url': { path: 'set-run-notice-url', app: true, flags: { value: list('url'), bool: list('clear') } },
+    'keys list': { path: 'keys/list', app: true, flags: {} },
+    'keys add': { path: 'keys/add', app: true, flags: { value: list('jwk', 'key-file') }, keyFile: true },
+    'keys retire': { path: 'keys/retire', app: true, flags: { value: list('kid') } },
+    'keys delete': { path: 'keys/delete', app: true, flags: { value: list('kid') } },
+    'keys set-jwks-uri': { path: 'keys/set-jwks-uri', app: true, flags: { value: list('jwks-uri') } },
+    'keys remove-jwks-uri': { path: 'keys/remove-jwks-uri', app: true, flags: { value: list('jwk', 'key-file') }, keyFile: true },
+    'testers list': { path: 'testers/list', app: true, flags: {} },
+    'testers add': { path: 'testers/add', app: true, flags: { value: list('email', 'phone') } },
+    'testers remove': { path: 'testers/remove', app: true, flags: { value: list('email', 'phone') } },
+};
+/** What a coding agent's login can't do, by CLI leaf name. */
+const REFUSED = {
+    'set-listing': 'list an app in the marketplace',
+    'set-spend-cap': "change an app's spend cap",
+    'set-allows': 'change what an app shares',
+    'provider get': "read an app's provider role",
+    'provider set': "change an app's provider role",
+    'provider refresh': "refresh an app's provider role",
+};
+const refusal = (leafName, issuer, app) => {
+    const appUrl = app ? `${issuer}/console/apps/${app}` : `${issuer}/console`;
+    if (leafName === 'delete')
+        return `Only you can delete an app, in the console: ${appUrl} → Profile → Delete this app.`;
+    return `A coding agent's Northlight login can't ${REFUSED[leafName]}. Do it in the console: ${appUrl}.`;
+};
+/** The `crouter-sdk apps <leaf>` command. Returns the process exit code. */
+export async function runApps(argv) {
+    const args = argv.slice(1);
+    const words = [];
+    while (words.length < 2 && args[0] !== undefined && !args[0].startsWith('--'))
+        words.push(args.shift());
+    // `keys list` has two words; `mine` has one. Put a second word back when the first is a one-word leaf.
+    let leafName = words.join(' ');
+    if (words.length === 2 && !(words[0] === 'keys' || words[0] === 'testers' || words[0] === 'provider')) {
+        args.unshift(words[1]);
+        leafName = words[0];
+    }
+    const leaf = Object.hasOwn(LEAVES, leafName) ? LEAVES[leafName] : undefined;
+    const base = leaf?.flags ?? {};
+    const spec = { value: ['--app', '--issuer', ...(base.value ?? [])], list: base.list, bool: ['--json', ...(base.bool ?? [])] };
+    let flags;
+    try {
+        if (!leafName)
+            throw new Error(USAGE);
+        flags = parseFlags(args, spec, USAGE);
+        if (flags.rest.length)
+            throw new Error(USAGE);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const envText = await readProjectEnv();
+    const issuer = resolveIssuer(flags.values.get('--issuer'), envText);
+    const appId = flags.values.get('--app') ?? (envText === undefined ? undefined : envValueOf(envText, 'CROUTER_CLIENT_ID'));
+    if (Object.hasOwn(REFUSED, leafName) || leafName === 'delete') {
+        console.error(refusal(leafName, issuer, appId));
+        return 1;
+    }
+    if (!leaf) {
+        console.error(`Unknown leaf \`${leafName}\`.\n${USAGE}`);
+        return 1;
+    }
+    if (leaf.app && !appId) {
+        console.error(`No app given. Pass --app <client id>, or set CROUTER_CLIENT_ID in ${ENV_PATH}.`);
+        return 1;
+    }
+    const params = {};
+    if (leaf.app)
+        params['app-id'] = appId;
+    for (const [flag, value] of flags.values)
+        if (flag !== '--app' && flag !== '--issuer' && flag !== '--key-file')
+            params[flag.slice(2)] = value;
+    for (const [flag, value] of flags.lists)
+        params[flag.slice(2)] = value;
+    for (const flag of flags.bools)
+        if (flag !== '--json')
+            params[flag.slice(2)] = true;
+    try {
+        const keyFile = flags.values.get('--key-file');
+        if (keyFile !== undefined) {
+            if (flags.values.has('--jwk')) {
+                console.error('Pass --jwk or --key-file, not both.');
+                return 1;
+            }
+            params.jwk = (await publicJwkFromFile(keyFile)).json;
+        }
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    try {
+        const session = await openSession(issuer, NOT_LOGGED_IN);
+        if (!session)
+            return 1;
+        console.log(JSON.stringify(await callLeaf(issuer, session.token.access_token, leaf.path, params), null, 2));
+        return 0;
+    }
+    catch (error) {
+        return reportFailure(error);
+    }
+}

package/dist/cli-usage.js

@@ -29,6 +29,38 @@ export const COMMANDS = [
         summary: 'Write `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env`, keeping every other line. `--client-id` makes no network call; `--app` reads them through crtr.',
         crtr: 'Only with `--app`',
     },
+    {
+        name: 'login',
+        forms: ['login [--no-browser] [--new] [--issuer <url>]'],
+        summary: 'Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out: it resumes the same code. Calls only the Northlight directory.',
+        crtr: 'No',
+    },
+    {
+        name: 'logout',
+        forms: ['logout [--issuer <url>]'],
+        summary: 'Revoke this computer\'s login on the server and delete it locally.',
+        crtr: 'No',
+    },
+    {
+        name: 'whoami',
+        forms: ['whoami [--issuer <url>]'],
+        summary: 'Show the account this computer is logged in as and when the login expires. Exits 1 when not logged in.',
+        crtr: 'No',
+    },
+    {
+        name: 'register',
+        forms: ['register [--name <text>] [--scope <scope>]... [--logo <url>] [--justification <text>] [--redirect-uri <uri>]... [--issuer <url>]'],
+        summary: 'Run in a project made by `init`, after `login`: registers the app with the public key from `local/app-key.json`, adds each `--scope` beyond `crtr:llm crtr:act`, and writes `CROUTER_CLIENT_ID` and `CROUTER_ISSUER` to `local/app.env`.',
+        crtr: 'No',
+    },
+    {
+        name: 'apps',
+        forms: [
+            'apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]',
+        ],
+        summary: 'Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only.',
+        crtr: 'No',
+    },
 ];
 const BIN = 'crouter-sdk';
 /** The usage text a command prints on a usage error. */

package/dist/credentials.d.ts

@@ -0,0 +1,36 @@
+export interface PendingLogin {
+    /** `nld_…`, generated by the CLI and written before the start request is sent. */
+    secret: string;
+    name: string;
+    started_at: string;
+    device_code?: string;
+    user_code?: string;
+    verification_uri_complete?: string;
+    expires_at?: string;
+}
+export interface IssuerEntry {
+    credential?: string;
+    credential_id?: string;
+    name?: string;
+    account_id?: string;
+    account_display?: string;
+    expires_at?: string;
+    pending?: PendingLogin;
+}
+export interface CredentialStore {
+    version: 1;
+    issuers: Record<string, IssuerEntry>;
+}
+export declare class CredentialFileError extends Error {
+}
+export declare const issuerKey: (issuer: string) => string;
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+/** `~/…` when the path is under the home directory. */
+export declare function displayPath(path: string): string;
+/** A fresh credential secret: `nld_` and 43 base64url characters (32 random bytes). */
+export declare const newSecret: () => string;
+export declare function loadStore(path?: string): Promise<CredentialStore>;
+/** Writes the store atomically (temporary file at 0600, then rename); the directory is created at 0700. */
+export declare function saveStore(store: CredentialStore, path?: string): Promise<void>;
+/** Replaces one issuer's entry (or removes it when `entry` is undefined or empty) and saves. */
+export declare function updateEntry(issuer: string, change: (entry: IssuerEntry) => IssuerEntry | undefined, path?: string): Promise<IssuerEntry | undefined>;

package/dist/credentials.js

@@ -0,0 +1,71 @@
+// The developer login store: ~/.config/northlight/credentials.json (or $XDG_CONFIG_HOME/northlight/), per issuer, mode 0600.
+// It does no network I/O. The pending entry holds the secret before the directory knows anything, so a killed `login` can resume.
+import { randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export class CredentialFileError extends Error {
+}
+export const issuerKey = (issuer) => issuer.replace(/\/+$/, '');
+export function credentialsPath(env = process.env) {
+    const base = env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME !== '' ? env.XDG_CONFIG_HOME : join(env.HOME && env.HOME !== '' ? env.HOME : homedir(), '.config');
+    return join(base, 'northlight', 'credentials.json');
+}
+/** `~/…` when the path is under the home directory. */
+export function displayPath(path) {
+    const home = process.env.HOME && process.env.HOME !== '' ? process.env.HOME : homedir();
+    return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+/** A fresh credential secret: `nld_` and 43 base64url characters (32 random bytes). */
+export const newSecret = () => `nld_${randomBytes(32).toString('base64url')}`;
+export async function loadStore(path = credentialsPath()) {
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { version: 1, issuers: {} };
+        throw error;
+    }
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        throw new CredentialFileError(`${displayPath(path)} can be read by other users (mode ${(info.mode & 0o777).toString(8)}), so it was not used. Run \`chmod 600 ${path}\`, or delete it and run \`npx @north-light/sdk login\`.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new CredentialFileError(`${displayPath(path)} is not valid JSON. Delete it and run \`npx @north-light/sdk login\`.`);
+    }
+    const issuers = parsed?.issuers;
+    if (!issuers || typeof issuers !== 'object')
+        return { version: 1, issuers: {} };
+    return { version: 1, issuers: issuers };
+}
+/** Writes the store atomically (temporary file at 0600, then rename); the directory is created at 0700. */
+export async function saveStore(store, path = credentialsPath()) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+        await chmod(temporary, 0o600);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+/** Replaces one issuer's entry (or removes it when `entry` is undefined or empty) and saves. */
+export async function updateEntry(issuer, change, path = credentialsPath()) {
+    const store = await loadStore(path);
+    const key = issuerKey(issuer);
+    const next = change({ ...store.issuers[key] });
+    if (next && Object.keys(next).length > 0)
+        store.issuers[key] = next;
+    else
+        delete store.issuers[key];
+    await saveStore(store, path);
+    return store.issuers[key];
+}

package/dist/developer-common.d.ts

@@ -0,0 +1,47 @@
+import { type IssuerEntry } from './credentials.js';
+import { DirectoryError, type TokenAnswer } from './directory-client.js';
+export declare const ENV_PATH = "local/app.env";
+export declare const DEFAULT_KEY_FILE = "local/app-key.json";
+export declare const LOGIN_COMMAND = "npx @north-light/sdk login";
+export interface FlagSpec {
+    value?: string[];
+    list?: string[];
+    bool?: string[];
+}
+export interface Flags {
+    values: Map<string, string>;
+    lists: Map<string, string[]>;
+    bools: Set<string>;
+    rest: string[];
+}
+/** Parses `--name value`, repeatable `--name value`, and `--name` flags; anything else is returned in `rest`. Throws `usage` on a bad flag. */
+export declare function parseFlags(args: string[], spec: FlagSpec, usage: string): Flags;
+export declare const trimIssuer: (issuer: string) => string;
+/** The project's local/app.env text, or undefined when there is none. */
+export declare const readProjectEnv: () => Promise<string | undefined>;
+/** `--issuer`, else (for commands that read the project) `CROUTER_ISSUER` from local/app.env, else production. */
+export declare function resolveIssuer(flag: string | undefined, envText?: string): string;
+/** The public half of a private JWK: every private member dropped. */
+export declare function publicJwkOf(privateJwk: Record<string, unknown>): Record<string, unknown>;
+/** Reads a private key file and returns its public JWK (as JSON text) and key id. The private half is never returned. */
+export declare function publicJwkFromFile(path: string): Promise<{
+    json: string;
+    kid: string;
+}>;
+/** `<code>: <message>` then `Next: <next>`, the way every directory error is printed. */
+export declare function directoryErrorLines(error: DirectoryError): string[];
+export declare const NOT_LOGGED_IN = "Not logged in. Run `npx @north-light/sdk login`.";
+/** Prints the message for a failure every command shares and returns exit code 1; rethrows anything else. */
+export declare function reportFailure(error: unknown): number;
+export interface Session {
+    issuer: string;
+    entry: IssuerEntry & {
+        credential: string;
+    };
+    token: TokenAnswer;
+}
+/**
+ * Loads the issuer's credential and exchanges it for a 5-minute token. Returns undefined, having printed why
+ * (`missing` is the message for no credential), when the command cannot go on. `onRejected` runs on a 401.
+ */
+export declare function openSession(issuer: string, missing: string, onRejected?: () => Promise<void>): Promise<Session | undefined>;

package/dist/developer-common.js

@@ -0,0 +1,112 @@
+// What the developer commands (login, logout, whoami, register, apps) share: flag parsing, issuer resolution, the
+// project's env file, the key file's public half, and the sign-in step with its error output.
+import { readFile } from 'node:fs/promises';
+import { CredentialFileError, issuerKey, loadStore } from './credentials.js';
+import { DirectoryError, NetworkError, exchange } from './directory-client.js';
+import { DEFAULT_ISSUER, envValueOf } from './env-command.js';
+import { parsePrivateJwk } from './oauth/keygen.js';
+export const ENV_PATH = 'local/app.env';
+export const DEFAULT_KEY_FILE = 'local/app-key.json';
+export const LOGIN_COMMAND = 'npx @north-light/sdk login';
+/** Parses `--name value`, repeatable `--name value`, and `--name` flags; anything else is returned in `rest`. Throws `usage` on a bad flag. */
+export function parseFlags(args, spec, usage) {
+    const out = { values: new Map(), lists: new Map(), bools: new Set(), rest: [] };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            out.rest.push(arg);
+            continue;
+        }
+        if (spec.bool?.includes(arg)) {
+            out.bools.add(arg);
+            continue;
+        }
+        const isValue = spec.value?.includes(arg);
+        const isList = spec.list?.includes(arg);
+        const next = args[++i];
+        if ((!isValue && !isList) || next === undefined || next.startsWith('--') || next === '')
+            throw new Error(usage);
+        if (isValue) {
+            if (out.values.has(arg))
+                throw new Error(usage);
+            out.values.set(arg, next);
+        }
+        else
+            out.lists.set(arg, [...(out.lists.get(arg) ?? []), next]);
+    }
+    return out;
+}
+export const trimIssuer = (issuer) => issuerKey(issuer);
+/** The project's local/app.env text, or undefined when there is none. */
+export const readProjectEnv = () => readFile(ENV_PATH, 'utf8').catch((error) => {
+    if (error.code === 'ENOENT')
+        return undefined;
+    throw error;
+});
+/** `--issuer`, else (for commands that read the project) `CROUTER_ISSUER` from local/app.env, else production. */
+export function resolveIssuer(flag, envText) {
+    return trimIssuer(flag ?? (envText === undefined ? undefined : envValueOf(envText, 'CROUTER_ISSUER')) ?? DEFAULT_ISSUER);
+}
+/** The public half of a private JWK: every private member dropped. */
+export function publicJwkOf(privateJwk) {
+    const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, oth: _oth, k: _k, ...rest } = privateJwk;
+    return rest;
+}
+/** Reads a private key file and returns its public JWK (as JSON text) and key id. The private half is never returned. */
+export async function publicJwkFromFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`${path} could not be read (${error instanceof Error ? error.message : String(error)}). Make one with \`npx @north-light/sdk keygen --out ${path}\`.`);
+    }
+    const key = parsePrivateJwk(text, path);
+    return { json: JSON.stringify(publicJwkOf(key)), kid: key.kid };
+}
+/** `<code>: <message>` then `Next: <next>`, the way every directory error is printed. */
+export function directoryErrorLines(error) {
+    return [`${error.code}: ${error.message}`, ...(error.next ? [`Next: ${error.next}`] : [])];
+}
+export const NOT_LOGGED_IN = `Not logged in. Run \`${LOGIN_COMMAND}\`.`;
+/** Prints the message for a failure every command shares and returns exit code 1; rethrows anything else. */
+export function reportFailure(error) {
+    if (error instanceof NetworkError) {
+        console.error(error.message);
+        return 1;
+    }
+    if (error instanceof DirectoryError) {
+        console.error(directoryErrorLines(error).join('\n'));
+        return 1;
+    }
+    if (error instanceof CredentialFileError) {
+        console.error(error.message);
+        return 1;
+    }
+    throw error;
+}
+/**
+ * Loads the issuer's credential and exchanges it for a 5-minute token. Returns undefined, having printed why
+ * (`missing` is the message for no credential), when the command cannot go on. `onRejected` runs on a 401.
+ */
+export async function openSession(issuer, missing, onRejected) {
+    const store = await loadStore();
+    const entry = store.issuers[issuer];
+    if (!entry?.credential) {
+        console.error(missing);
+        return undefined;
+    }
+    try {
+        const token = await exchange(issuer, entry.credential);
+        return { issuer, entry: entry, token };
+    }
+    catch (error) {
+        if (error instanceof DirectoryError && error.status === 401) {
+            console.error(error.message);
+            await onRejected?.();
+            return undefined;
+        }
+        reportFailure(error);
+        return undefined;
+    }
+}

package/dist/directory-client.d.ts

@@ -0,0 +1,46 @@
+export declare class DirectoryError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly next?: string | undefined;
+    constructor(status: number, code: string, message: string, next?: string | undefined);
+}
+export declare class NetworkError extends Error {
+    readonly issuer: string;
+    readonly reason: string;
+    constructor(issuer: string, reason: string);
+}
+export declare const sha256Hex: (text: string) => string;
+export interface Account {
+    id: string;
+    display: string;
+}
+export interface LoginStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export type PollResult = {
+    status: 'pending' | 'slow_down' | 'access_denied' | 'expired_token';
+} | {
+    status: 'approved';
+    credential_id: string;
+    account: Account;
+    expires_at: string;
+    idle_days: number;
+};
+export interface TokenAnswer {
+    access_token: string;
+    credential_id: string;
+    account: Account;
+    expires_at: string;
+}
+export declare function startLogin(issuer: string, secret: string, name: string): Promise<LoginStart>;
+export declare function pollLogin(issuer: string, deviceCode: string): Promise<PollResult>;
+export declare function exchange(issuer: string, secret: string): Promise<TokenAnswer>;
+export declare function revokeCredential(issuer: string, secret: string): Promise<void>;
+/** One developer leaf of the `cloud` plugin: `leaf` is its path under `apps`, `params` the leaf's kebab-case parameters. */
+export declare function callLeaf(issuer: string, accessToken: string, leaf: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare const machineName: () => string;

package/dist/directory-client.js

@@ -0,0 +1,105 @@
+// Every HTTP call the developer CLI makes to the directory. It maps directory errors to DirectoryError and network
+// failures to NetworkError; it owns no output text beyond those messages.
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname, platform } from 'node:os';
+import { SDK_VERSION } from './version.js';
+export class DirectoryError extends Error {
+    status;
+    code;
+    next;
+    constructor(status, code, message, next) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.next = next;
+    }
+}
+export class NetworkError extends Error {
+    issuer;
+    reason;
+    constructor(issuer, reason) {
+        super(`Couldn't reach ${issuer} (${reason}). To register without logging in, use the console: ${issuer}/console/new`);
+        this.issuer = issuer;
+        this.reason = reason;
+    }
+}
+export const sha256Hex = (text) => createHash('sha256').update(text).digest('hex');
+function errorOf(body, status) {
+    const record = (body && typeof body === 'object' ? body : {});
+    const error = record.error;
+    if (error && typeof error === 'object') {
+        const e = error;
+        return { code: String(e.code ?? 'error'), message: String(e.message ?? `HTTP ${status}`), ...(typeof e.next === 'string' ? { next: e.next } : {}) };
+    }
+    if (typeof error === 'string')
+        return { code: error, message: String(record.error_description ?? record.message ?? error) };
+    return { code: 'error', message: `The directory answered HTTP ${status}.` };
+}
+async function request(issuer, path, init) {
+    let response;
+    try {
+        response = await fetch(`${issuer}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...init.headers },
+            body: JSON.stringify(init.body ?? {}),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        const cause = error.cause;
+        throw new NetworkError(issuer, cause?.code ?? cause?.message ?? (error instanceof Error ? error.message : String(error)));
+    }
+    const text = await response.text();
+    let body;
+    try {
+        body = text === '' ? {} : JSON.parse(text);
+    }
+    catch {
+        body = {};
+    }
+    return { status: response.status, body };
+}
+const fail = (status, body) => {
+    const e = errorOf(body, status);
+    throw new DirectoryError(status, e.code, e.message, e.next);
+};
+export async function startLogin(issuer, secret, name) {
+    const { status, body } = await request(issuer, '/v1/developer/logins', { body: {
+            credential_hash: sha256Hex(secret), name: name.slice(0, 64),
+            platform: platform() === 'darwin' || platform() === 'win32' ? platform() : 'linux', sdk_version: SDK_VERSION,
+        } });
+    if (status !== 200 && status !== 201)
+        fail(status, body);
+    return body;
+}
+export async function pollLogin(issuer, deviceCode) {
+    const { status, body } = await request(issuer, '/v1/developer/logins/poll', { body: { device_code: deviceCode } });
+    if (status === 200)
+        return { ...body, status: 'approved' };
+    const code = errorOf(body, status).code;
+    if (status === 400 && (code === 'authorization_pending' || code === 'slow_down' || code === 'access_denied' || code === 'expired_token')) {
+        return { status: code === 'authorization_pending' ? 'pending' : code };
+    }
+    return fail(status, body);
+}
+export async function exchange(issuer, secret) {
+    const { status, body } = await request(issuer, '/v1/developer/token', { headers: { authorization: `Bearer ${secret}` } });
+    if (status !== 200)
+        fail(status, body);
+    return body;
+}
+export async function revokeCredential(issuer, secret) {
+    const { status, body } = await request(issuer, '/v1/developer/token/revoke', { headers: { authorization: `Bearer ${secret}` } });
+    if (status !== 200)
+        fail(status, body);
+}
+/** One developer leaf of the `cloud` plugin: `leaf` is its path under `apps`, `params` the leaf's kebab-case parameters. */
+export async function callLeaf(issuer, accessToken, leaf, params) {
+    const { status, body } = await request(issuer, `/v1/plugin/v1/cloud/apps/${leaf}`, {
+        headers: { authorization: `Bearer ${accessToken}`, 'crtr-request-id': randomUUID() }, body: params,
+    });
+    if (status !== 200)
+        fail(status, body);
+    return body;
+}
+export const machineName = () => hostname().slice(0, 64);

package/dist/init-command.js

@@ -11,6 +11,7 @@ import { createKeyFile } from './keygen-command.js';
 import { isAgent, packagedSkill, skillTargets, writeSkillFile } from './skill-command.js';
 import { SDK_VERSION } from './version.js';
 const CONSOLE_URL = 'https://account.northlight.ai/console/new';
+const QUICKSTART_URL = 'https://sdk.docs.northlight.ai/docs/quickstart';
 const KEY_FILE = 'local/app-key.json';
 const ENV_FILE = 'local/app.env';
 const START = 'node --env-file=local/app.env --import tsx server.ts';
@@ -93,6 +94,41 @@ function installSdk(cwd) {
     }
     return result.status ?? 1;
 }
+/** The "Next" text when `register` can run: log in, register, start. */
+function agentNext(cd, existingProject) {
+    return [
+        'Next, in this order:',
+        "  1. Sign up at https://account.northlight.ai/signup if you don't have an account.",
+        '  2. npx @north-light/sdk login        (you approve once in the browser)',
+        '  3. npx @north-light/sdk register --scope sms:send',
+        '  4. Start it:',
+        ...cd.map((line) => `       ${line}`),
+        ...(existingProject ? [] : ['       npm i']),
+        `       ${START}`,
+        `     then open ${DEFAULT_ORIGIN}/auth/login`,
+        `To register in the browser instead: ${CONSOLE_URL} (see ${QUICKSTART_URL}).`,
+    ];
+}
+/** The "Next" text for an existing project with no local/app.env, where `register` has no origin to read: the console path. */
+function consoleNext(cd, existingProject, jwkOnStdout) {
+    return [
+        'Next, in this order:',
+        "  1. Sign up at https://account.northlight.ai/signup if you don't have an account.",
+        `  2. Register the app at ${CONSOLE_URL} with these values:`,
+        `       Origin URL:    ${DEFAULT_ORIGIN}`,
+        `       Redirect URI:  ${DEFAULT_ORIGIN}/auth/callback`,
+        ...(jwkOnStdout ? ['       Public key:    the JWK printed on stdout'] : [`       Public key:    the public half of ${KEY_FILE}`]),
+        '     Then open the app\'s "What it asks for" tab, choose Add permissions, and add sms:send.',
+        '  3. Write the client ID the console shows into the env file:',
+        '       npx @north-light/sdk env --client-id <client id>',
+        '  4. Start it:',
+        ...cd.map((line) => `       ${line}`),
+        ...(existingProject ? [] : ['       npm i']),
+        `       ${START}`,
+        `     then open ${DEFAULT_ORIGIN}/auth/login`,
+        `Steps: ${QUICKSTART_URL}`,
+    ];
+}
 /** The `crouter-sdk init` command. Returns the process exit code. */
 export async function runInit(argv, options = {}) {
     const { dir: given, agent, globalSkill } = parseArgs(argv);
@@ -152,6 +188,8 @@ export async function runInit(argv, options = {}) {
     for (const path of skillPaths)
         await writeSkillFile(path, skill);
     const cd = given === '.' ? [] : [`cd ${given}`];
+    // `register` reads APP_ORIGIN from local/app.env, which init writes only for a new app.
+    const registerable = await exists(join(root, ENV_FILE));
     say([
         existingProject ? `Added @north-light/sdk@${SDK_VERSION}, a signing key and the \`northlight\` skill to ${shown(root)}.` : `Created a Northlight app in ${shown(root)}:`,
         ...(existingProject ? [] : ['  package.json  server.ts  .gitignore  local/app.env', '']),
@@ -160,20 +198,7 @@ export async function runInit(argv, options = {}) {
         'Skill:',
         ...skillPaths.map((path) => `  ${globalSkill ? path : shown(path)}`),
         '',
-        'Next, in this order:',
-        "  1. Sign in at https://account.northlight.ai/signup if you don't have an account.",
-        `  2. Register the app at ${CONSOLE_URL} with these values:`,
-        `       Origin URL:    ${DEFAULT_ORIGIN}`,
-        `       Redirect URI:  ${DEFAULT_ORIGIN}/auth/callback`,
-        ...(publicJwk ? ['       Public key:    the JWK printed on stdout'] : [`       Public key:    the public half of ${KEY_FILE}`]),
-        '     Then open the app\'s "What it asks for" tab, choose Add permissions, and add sms:send.',
-        '  3. Write the client ID the console shows into the env file:',
-        '       npx @north-light/sdk env --client-id <client id>',
-        '  4. Start it:',
-        ...cd.map((line) => `       ${line}`),
-        ...(existingProject ? [] : ['       npm i']),
-        `       ${START}`,
-        `     then open ${DEFAULT_ORIGIN}/auth/login`,
+        ...(registerable ? agentNext(cd, existingProject) : consoleNext(cd, existingProject, publicJwk !== undefined)),
     ]);
     if (publicJwk)
         console.log(publicJwk);

package/dist/keygen-cli.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
-// The `crouter-sdk` bin: `init`, `skill`, `keygen` and `env`. The file keeps its first command's name because the
+// The `crouter-sdk` bin: `init`, `skill`, `keygen`, `env`, and the developer commands `login`, `logout`, `whoami`, `register` and `apps`. The file keeps its first command's name because the
 // published bin path (`dist/keygen-cli.js`) is part of the package, and the package keeps exactly one bin so that
 // `npx @north-light/sdk <command>` works without naming it.
 import { overviewUsage } from './cli-usage.js';
 import { runEnv } from './env-command.js';
 import { runInit } from './init-command.js';
 import { runKeygen } from './keygen-command.js';
+import { runApps } from './apps-command.js';
+import { runLogin } from './login-command.js';
+import { runLogout } from './logout-command.js';
+import { runRegister } from './register-command.js';
+import { runWhoami } from './whoami-command.js';
 import { runSkill } from './skill-command.js';
 const args = process.argv.slice(2);
-const commands = { init: runInit, skill: runSkill, keygen: runKeygen, env: runEnv };
+const commands = { init: runInit, skill: runSkill, keygen: runKeygen, env: runEnv, login: runLogin, logout: runLogout, whoami: runWhoami, register: runRegister, apps: runApps };
 const command = args[0] ?? '';
 async function main() {
     if (command === '--help' || command === '-h' || command === 'help') {

package/dist/login-command.d.ts

@@ -0,0 +1 @@
+export declare function runLogin(argv: string[]): Promise<number>;

package/dist/login-command.js

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { loadStore, newSecret, displayPath, credentialsPath, updateEntry } from './credentials.js';
+import { usageOf } from './cli-usage.js';
+import { NetworkError, DirectoryError, machineName, pollLogin, revokeCredential, startLogin } from './directory-client.js';
+import { parseFlags, reportFailure, resolveIssuer } from './developer-common.js';
+const USAGE = usageOf('login');
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The poll interval in ms. The directory says 5 s; tests shorten it with NORTHLIGHT_LOGIN_POLL_MS. */
+const intervalMs = () => Number(process.env.NORTHLIGHT_LOGIN_POLL_MS) || 5000;
+/** Tries to open `url` in a browser, detached. Resolves true when the opener started. */
+function openBrowser(url) {
+    if (process.env.CI)
+        return Promise.resolve(false);
+    let command;
+    let args;
+    if (process.platform === 'darwin') {
+        command = 'open';
+        args = [url];
+    }
+    else if (process.platform === 'win32') {
+        command = 'cmd';
+        args = ['/c', 'start', '""', url];
+    }
+    else if (process.env.DISPLAY || process.env.WAYLAND_DISPLAY) {
+        command = 'xdg-open';
+        args = [url];
+    }
+    else
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+            child.once('error', () => resolve(false));
+            child.once('spawn', () => { child.unref(); resolve(true); });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+const hhmm = (iso) => {
+    const date = new Date(iso);
+    return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+};
+export async function runLogin(argv) {
+    let flags;
+    try {
+        flags = parseFlags(argv.slice(1), { value: ['--issuer'], bool: ['--no-browser', '--new'] }, USAGE);
+        if (flags.rest.length)
+            throw new Error(USAGE);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const issuer = resolveIssuer(flags.values.get('--issuer'));
+    try {
+        const store = await loadStore();
+        let pending = store.issuers[issuer]?.pending;
+        const now = Date.now();
+        let resumed = false;
+        if (pending && (flags.bools.has('--new') || !pending.device_code || !pending.expires_at || Date.parse(pending.expires_at) <= now)) {
+            pending = undefined;
+            await updateEntry(issuer, ({ pending: _gone, ...rest }) => rest);
+        }
+        else if (pending)
+            resumed = true;
+        if (!pending) {
+            const fresh = { secret: newSecret(), name: machineName(), started_at: new Date().toISOString() };
+            // The secret is on disk before the directory hears anything about it.
+            await updateEntry(issuer, (entry) => ({ ...entry, pending: fresh }));
+            let start;
+            try {
+                start = await startLogin(issuer, fresh.secret, fresh.name);
+            }
+            catch (error) {
+                if (error instanceof DirectoryError && error.status === 404) {
+                    await updateEntry(issuer, ({ pending: _gone, ...rest }) => rest);
+                    console.error(`This Northlight directory doesn't support login yet. Register in the console: ${issuer}/console/new`);
+                    return 1;
+                }
+                throw error;
+            }
+            pending = { ...fresh, device_code: start.device_code, user_code: start.user_code,
+                verification_uri_complete: start.verification_uri_complete, expires_at: new Date(Date.now() + start.expires_in * 1000).toISOString() };
+            const saved = pending;
+            await updateEntry(issuer, (entry) => ({ ...entry, pending: saved }));
+        }
+        const url = pending.verification_uri_complete;
+        const code = pending.user_code;
+        if (resumed)
+            console.log(`Still waiting for the login started at ${hhmm(pending.started_at)}.`);
+        console.log(['To let this computer manage your Northlight apps, open:', '', `  ${url}`, '', `and check the page shows the code ${code}.`].join('\n'));
+        const opened = !flags.bools.has('--no-browser') && await openBrowser(url);
+        console.log(opened ? 'Opened it in your browser.' : "Couldn't open a browser here. Open the link on any device where you can sign in to Northlight.");
+        const minutes = Math.max(1, Math.round((Date.parse(pending.expires_at) - Date.now()) / 60_000));
+        console.log(`Waiting for approval (the code expires in ${minutes} minute${minutes === 1 ? '' : 's'})…`);
+        let wait = intervalMs();
+        const deadline = Date.parse(pending.expires_at) + 30_000;
+        for (;;) {
+            const answer = await pollLogin(issuer, pending.device_code);
+            if (answer.status === 'approved') {
+                const old = (await loadStore()).issuers[issuer]?.credential;
+                await updateEntry(issuer, () => ({
+                    credential: pending.secret, credential_id: answer.credential_id, name: pending.name,
+                    account_id: answer.account.id, account_display: answer.account.display, expires_at: answer.expires_at,
+                }));
+                if (old && old !== pending.secret)
+                    await revokeCredential(issuer, old).catch(() => undefined);
+                console.log([
+                    `Signed in as ${answer.account.display} (${answer.account.id}).`,
+                    `Saved the login for ${pending.name} to ${displayPath(credentialsPath())} (only you can read it).`,
+                    "It can register and configure the apps you manage. It can't delete an app.",
+                    `It expires on ${answer.expires_at.slice(0, 10)}, or after ${answer.idle_days ?? 14} days unused. Revoke it at ${issuer}/account/developer`,
+                ].join('\n'));
+                return 0;
+            }
+            if (answer.status === 'access_denied' || answer.status === 'expired_token') {
+                await updateEntry(issuer, ({ pending: _gone, ...rest }) => rest);
+                console.error(answer.status === 'access_denied'
+                    ? 'The login was declined in the browser. Nothing was saved.'
+                    : 'The code expired before it was approved. Run `npx @north-light/sdk login` again.');
+                return 1;
+            }
+            if (Date.now() > deadline) {
+                await updateEntry(issuer, ({ pending: _gone, ...rest }) => rest);
+                console.error('The code expired before it was approved. Run `npx @north-light/sdk login` again.');
+                return 1;
+            }
+            if (answer.status === 'slow_down')
+                wait += intervalMs();
+            await sleep(wait);
+        }
+    }
+    catch (error) {
+        if (error instanceof NetworkError) {
+            console.error(error.message);
+            return 1;
+        }
+        return reportFailure(error);
+    }
+}

package/dist/logout-command.d.ts

@@ -0,0 +1 @@
+export declare function runLogout(argv: string[]): Promise<number>;

package/dist/logout-command.js

@@ -0,0 +1,42 @@
+import { NetworkError, DirectoryError, revokeCredential } from './directory-client.js';
+import { loadStore, updateEntry } from './credentials.js';
+import { usageOf } from './cli-usage.js';
+import { NOT_LOGGED_IN, parseFlags, reportFailure, resolveIssuer } from './developer-common.js';
+export async function runLogout(argv) {
+    let flags;
+    try {
+        flags = parseFlags(argv.slice(1), { value: ['--issuer'] }, usageOf('logout'));
+        if (flags.rest.length)
+            throw new Error(usageOf('logout'));
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const issuer = resolveIssuer(flags.values.get('--issuer'));
+    try {
+        const entry = (await loadStore()).issuers[issuer];
+        if (!entry?.credential) {
+            console.error(NOT_LOGGED_IN);
+            return 1;
+        }
+        const name = entry.name ?? 'this computer';
+        await updateEntry(issuer, () => undefined);
+        try {
+            await revokeCredential(issuer, entry.credential);
+        }
+        catch (error) {
+            if (error instanceof NetworkError) {
+                console.error(`Removed the login from this computer. Couldn't reach ${issuer} to revoke it; revoke it at ${issuer}/account/developer`);
+                return 1;
+            }
+            if (!(error instanceof DirectoryError && error.status === 401))
+                throw error;
+        }
+        console.log(`Logged out. The login for ${name} is revoked.`);
+        return 0;
+    }
+    catch (error) {
+        return reportFailure(error);
+    }
+}

package/dist/register-command.d.ts

@@ -0,0 +1,2 @@
+/** The `crouter-sdk register` command. Returns the process exit code. */
+export declare function runRegister(argv: string[]): Promise<number>;

package/dist/register-command.js

@@ -0,0 +1,111 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { usageOf } from './cli-usage.js';
+import { callLeaf } from './directory-client.js';
+import { envValueOf, keyFileOf, updateEnvText } from './env-command.js';
+import { DEFAULT_KEY_FILE, ENV_PATH, LOGIN_COMMAND, openSession, parseFlags, publicJwkFromFile, readProjectEnv, reportFailure, resolveIssuer } from './developer-common.js';
+import { DEFAULT_ISSUER } from './env-command.js';
+const USAGE = usageOf('register');
+const DEFAULT_LOGO = 'https://sdk.docs.northlight.ai/app-logo.png';
+const BASE_SCOPES = ['crtr:llm', 'crtr:act'];
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
+async function defaultName() {
+    try {
+        const name = JSON.parse(await readFile('package.json', 'utf8')).name;
+        if (typeof name === 'string' && name !== '')
+            return name;
+    }
+    catch { /* no package.json: fall through to the directory name */ }
+    return basename(resolve('.'));
+}
+/** The `crouter-sdk register` command. Returns the process exit code. */
+export async function runRegister(argv) {
+    let flags;
+    try {
+        flags = parseFlags(argv.slice(1), { value: ['--name', '--logo', '--justification', '--issuer'], list: ['--scope', '--redirect-uri'] }, USAGE);
+        if (flags.rest.length)
+            throw new Error(USAGE);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const envText = await readProjectEnv();
+    if (envText === undefined) {
+        console.error(`No ${ENV_PATH} here. Run this in a project made by \`npx @north-light/sdk init\`.`);
+        return 1;
+    }
+    const existingId = envValueOf(envText, 'CROUTER_CLIENT_ID');
+    if (existingId) {
+        console.error(`This project is already registered as ${existingId}. Change it with \`npx @north-light/sdk apps …\`.`);
+        return 1;
+    }
+    const origin = envValueOf(envText, 'APP_ORIGIN');
+    if (!origin) {
+        console.error(`${ENV_PATH} has no APP_ORIGIN. Set it to where the app is served, for example http://localhost:3000.`);
+        return 1;
+    }
+    const keyFile = keyFileOf(envText) ?? DEFAULT_KEY_FILE;
+    let key;
+    try {
+        key = await publicJwkFromFile(keyFile);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const issuer = resolveIssuer(flags.values.get('--issuer'), envText);
+    const name = flags.values.get('--name') ?? await defaultName();
+    const logo = flags.values.get('--logo') ?? DEFAULT_LOGO;
+    const justification = flags.values.get('--justification') ?? `${name} is in development.`;
+    const redirectUris = flags.lists.get('--redirect-uri') ?? [`${origin.replace(/\/+$/, '')}/auth/callback`];
+    const scopes = flags.lists.get('--scope') ?? [];
+    try {
+        const session = await openSession(issuer, `Not logged in. Run \`${LOGIN_COMMAND}\` first, or register in the console: ${issuer}/console/new`);
+        if (!session)
+            return 1;
+        const token = session.token.access_token;
+        const app = await callLeaf(issuer, token, 'register', {
+            name, origin, logo, justification, 'redirect-uri': redirectUris, jwk: key.json,
+        });
+        const clientId = String(app.client_id ?? '');
+        if (!clientId) {
+            console.error('The directory registered the app but did not answer its client ID. Find it with `npx @north-light/sdk apps mine`.');
+            return 1;
+        }
+        // Written before the scopes call, so a failure there leaves the env file complete.
+        await writeFile(ENV_PATH, updateEnvText(envText, { CROUTER_ISSUER: issuer, CROUTER_CLIENT_ID: clientId, APP_ORIGIN: origin }));
+        const registered = strings(app.requested_scopes) ?? BASE_SCOPES;
+        const summary = (asks) => [
+            `Registered ${name} (client ID ${clientId}). It is in testing: only you and your testers can sign in.`,
+            `  Origin:        ${origin}`,
+            `  Redirect URI:  ${strings(app.redirect_uris)?.join(' ') ?? redirectUris.join(' ')}`,
+            `  Public key:    ${key.kid} (from ${keyFile})`,
+            `  Asks for:      ${asks.join(' ')}`,
+            `Wrote CROUTER_CLIENT_ID to ${ENV_PATH}.`,
+        ];
+        let asks = registered;
+        if (scopes.length > 0) {
+            try {
+                const updated = await callLeaf(issuer, token, 'set-scopes', { 'app-id': clientId, add: scopes });
+                asks = strings(updated.requested_scopes) ?? [...registered, ...scopes.filter((scope) => !registered.includes(scope))];
+            }
+            catch (error) {
+                console.log(summary(registered).join('\n'));
+                const message = error instanceof Error ? error.message : String(error);
+                const issuerFlag = issuer === DEFAULT_ISSUER ? '' : ` --issuer ${issuer}`;
+                console.error(`Couldn't add the scopes: ${message}. Run: npx @north-light/sdk apps set-scopes ${scopes.map((scope) => `--add ${scope}`).join(' ')}${issuerFlag}`);
+                return 1;
+            }
+        }
+        console.log([
+            ...summary(asks),
+            `Console: ${issuer}/console/apps/${clientId}`,
+            `Next: npm i && npm start, then open ${origin.replace(/\/+$/, '')}/auth/login`,
+        ].join('\n'));
+        return 0;
+    }
+    catch (error) {
+        return reportFailure(error);
+    }
+}

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.479"
+  sdk-version: "0.3.481"
 ---
 
 # Building a Northlight app
@@ -11,37 +11,29 @@ An app on Northlight signs people in with their Northlight account, then starts
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.479`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.481`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 
 - **Your server** runs wherever you choose (your laptop while developing). It holds the app's private signing key and each person's stored connection.
-- **account.northlight.ai** is the directory. People sign up and consent there. You register the app in its web console, `https://account.northlight.ai/console`.
+- **account.northlight.ai** is the directory. People sign up and consent there. You register the app with `npx @north-light/sdk register`, or in its web console, `https://account.northlight.ai/console`.
 - **The person's runtime** runs their agents. Your server reaches it with `oauth.client(userId)` and calls `runs.*` and `providers.*` on it.
 
-An app signs requests with a key pair, not a client secret. The private key stays in `local/app-key.json`; the console holds only the public key.
+An app signs requests with a key pair, not a client secret. The private key stays in `local/app-key.json`; the directory holds only the public key.
 
 ## The journey
 
-You do the command-line steps. The person does the console steps in a browser: ask them, name the exact field labels, and wait for the values you need back (the client ID).
+You run the commands. The person does two things in a browser: signs up, and chooses Allow (on a login page, then on the app's consent page). Everything else is yours.
 
 1. **Account (person).** They sign up at `https://account.northlight.ai/signup`. Signup texts a code over iMessage, so the phone must have iMessage.
-2. **Scaffold (you).** In a new folder run `npx @north-light/sdk@latest init my-app`. In an existing Node project run `npx @north-light/sdk init` instead: it adds the SDK pinned to an exact version, a key and this skill, and overwrites nothing. It prints the public JWK on stdout. `local/app.env` gets the issuer, the origin `http://localhost:3000`, and an empty `CROUTER_CLIENT_ID=`.
-3. **Register (person).** At `https://account.northlight.ai/console/new`, under **Register an app**, they fill in:
-   - **Name**, shown on the consent page.
-   - **Origin URL**: `http://localhost:3000` for development.
-   - **Logo URL**: a square image.
-   - **Why your app needs access**: one sentence, quoted to people on the consent page.
-   - **Redirect URIs**: `http://localhost:3000/auth/callback`. Sign-in returns only to a URI listed here, matched exactly, so `localhost` and `127.0.0.1` differ and the port counts.
-   - **Public key**: the JWK that `init` printed. Never ask for, accept or paste the private key.
-
-   The console then shows the **client ID**. Ask for it.
-4. **Say what the app asks for (person).** On the app's **What it asks for** tab, **Add permissions**, then add every provider scope the code requests (the quickstart needs `sms:send`: choose Texting, tick it, choose **Done**, then choose **Save**; **Done** alone stores nothing). A new app starts with `crtr:llm` and `crtr:act`. Without a scope listed here the consent page does not offer it and the provider call is refused ([Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)).
-5. **Write the env file (you).** `npx @north-light/sdk env --client-id <client id>`. It sets `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` in `local/app.env` and keeps every other line.
-6. **Run it (you).** `npm i`, then `node --env-file=local/app.env --import tsx server.ts`. Ask the person to open `http://localhost:3000/auth/login`, sign in, and choose Allow. The page then starts a run and sends them a text.
-7. **Testing mode.** A new app is in testing: only its owner and up to 100 testers can sign in. Testers are added by email or phone on the console's **Testers** tab. Anyone else's callback gets `error=access_denied` with `error_description=app_in_testing` ([Testing mode](https://sdk.docs.northlight.ai/docs/concepts/testing-mode.md)). Going public needs verification: email support@northlight.ai.
-
-Check each step worked before the next: a `local/app-key.json` file exists, a client ID is in `local/app.env`, the server prints `Listening on http://localhost:3000`, `/auth/login` reaches the Northlight consent page, and the callback lands back on your server. If a step fails, read the error and the page it names before changing code.
+2. **Scaffold (you).** In a new folder run `npx @north-light/sdk@latest init my-app`. In an existing Node project run `npx @north-light/sdk init` instead: it adds the SDK pinned to an exact version, a key and this skill, and overwrites nothing. A new app gets `local/app.env` with the issuer, the origin `http://localhost:3000` and an empty `CROUTER_CLIENT_ID=`.
+3. **Log in (you run it, the person approves).** Run `npx @north-light/sdk login`. It prints a link and a code. Show the person the link and the code exactly as printed and ask them to open the link, check the page shows the same code, and choose **Allow**. If your command times out first, run `login` again: it resumes the same code (do not pass `--new`). `npx @north-light/sdk whoami` checks the login. If `login` cannot reach `account.northlight.ai`, use step 7.
+4. **Register (you).** For the quickstart app run `npx @north-light/sdk register --scope sms:send`. `sms:send` is the scope `server.ts` requests. It registers the app with the public key from `local/app-key.json`, adds the scope and writes `CROUTER_CLIENT_ID` to `local/app.env`. For any other provider scope: register first, find the string with `npx @north-light/sdk apps asks` (it needs the registered app), then add it with `npx @north-light/sdk apps set-scopes --add <scope>`. Never invent a scope string ([Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)).
+5. **Run it (you, then the person).** `npm i`, then `npm start`. Ask the person to open `http://localhost:3000/auth/login`, sign in and choose **Allow**. The page then starts a run and sends them a text.
+6. **Testing mode.** A new app is in testing: only its owner and up to 100 testers can sign in. Add one with `npx @north-light/sdk apps testers add --email <email>`. Anyone else's callback gets `error=access_denied` with `error_description=app_in_testing` ([Testing mode](https://sdk.docs.northlight.ai/docs/concepts/testing-mode.md)). Going public needs verification: email support@northlight.ai.
+7. **If login is not possible** (no network to `account.northlight.ai`, or the person prefers the browser): they register at `https://account.northlight.ai/console/new`. Ask them to fill in **Name**, **Origin URL** (`http://localhost:3000`), **Logo URL** (a square image), **Why your app needs access** (one sentence) and **Redirect URIs** (`http://localhost:3000/auth/callback`, matched exactly), and to paste the public JWK that `init` printed. Never ask for or accept the private key. On the app's **What it asks for** tab they choose **Add permissions**, add `sms:send` and choose **Save** (**Done** alone stores nothing). Ask for the client ID the console shows, then run `npx @north-light/sdk env --client-id <client id>`.
+
+Check each step worked before the next: a `local/app-key.json` file exists, `whoami` names the person, a client ID is in `local/app.env`, the server prints `Listening on http://localhost:3000`, `/auth/login` reaches the Northlight consent page, and the callback lands back on your server. If a step fails, read the error and the page it names before changing code.
 
 ## Code patterns
 
@@ -153,8 +145,10 @@ export async function textMe(runtime: ConnectedCrouter, body: string) {
 Details behind each rule: [Errors](https://sdk.docs.northlight.ai/docs/errors.md), [Typed results](https://sdk.docs.northlight.ai/docs/guides/typed-results.md), [Connections](https://sdk.docs.northlight.ai/docs/concepts/connections.md).
 
 - **Pin the exact SDK version** (`npm i --save-exact`). A later release can change a type or method, and `^` picks it up on the next `npm i`.
-- **Take scope strings from the console's Add permissions list or from `providers.tools`.** Never invent one. Tool names and arguments also come from `providers.tools('<provider>')`.
-- **Never print, paste, log or commit `local/app-key.json`.** `local/` is in `.gitignore`. If it leaks, add a new key in the console, switch to it, and retire the old one.
+- **Take scope strings from `npx @north-light/sdk apps asks`, the console's Add permissions list or `providers.tools`.** Never invent one. Tool names and arguments also come from `providers.tools('<provider>')`.
+- **Never print, paste, log or commit `local/app-key.json`, `~/.config/northlight/credentials.json` or any `nld_` value.** `local/` is in `.gitignore`. If the app key leaks, add a new key in the console, switch to it, and retire the old one.
+- **Do not run `logout` unless the person asks.** It revokes the login and the next session must ask them to approve again.
+- **Deleting an app, listing it in the marketplace, its spend cap and sharing are the person's, in the console** (`https://account.northlight.ai/console`). Name the page; do not try the CLI, which refuses. On a verified app, signing keys, the JWKS URL, redirect URIs and the run notice URL change there too ([Manage your app](https://sdk.docs.northlight.ai/docs/guides/manage-your-app.md)).
 - **Use `oauth.client(userId)` for a person's runtime. Never `new Crouter()`.** `Crouter` is the client for a runtime you run yourself, not for apps.
 - **Use a persistent `ConnectionStore` in production.** `MemoryConnectionStore` loses every sign-in on restart and does not work across processes. `@north-light/sdk/stores/postgres` is the production store.
 - **Use `runs.parse` with a schema for data. Never parse `runs.trace`.** The trace is what the model said; `output_parsed` is a value checked against your schema.
@@ -172,6 +166,11 @@ Details behind each rule: [Errors](https://sdk.docs.northlight.ai/docs/errors.md
 | `skill [--agent claude|agents|all] [--global] [--print]` | Write the packaged `northlight` skill into `.agents/skills` and `.claude/skills` (or `~/` with `--global`), replacing an older copy. `--print` writes it to stdout. | No |
 | `keygen [--out <path>] [--app <client id>] [--yes]` | Write a private signing key to `local/app-key.json` (mode 0600) and print the public JWK to register. | Only with `--app` |
 | `env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]`<br>`env --app <client id> [--out <path>]` | Write `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env`, keeping every other line. `--client-id` makes no network call; `--app` reads them through crtr. | Only with `--app` |
+| `login [--no-browser] [--new] [--issuer <url>]` | Log this computer in to your Northlight account: prints a link and a code, you approve once in the browser, and a revocable login is saved to `~/.config/northlight/credentials.json`. Run it again if it times out: it resumes the same code. Calls only the Northlight directory. | No |
+| `logout [--issuer <url>]` | Revoke this computer's login on the server and delete it locally. | No |
+| `whoami [--issuer <url>]` | Show the account this computer is logged in as and when the login expires. Exits 1 when not logged in. | No |
+| `register [--name <text>] [--scope <scope>]... [--logo <url>] [--justification <text>] [--redirect-uri <uri>]... [--issuer <url>]` | Run in a project made by `init`, after `login`: registers the app with the public key from `local/app-key.json`, adds each `--scope` beyond `crtr:llm crtr:act`, and writes `CROUTER_CLIENT_ID` and `CROUTER_ISSUER` to `local/app.env`. | No |
+| `apps <leaf> [--app <client id>] [--issuer <url>] [leaf flags] [--json]` | Call one app-management leaf with the login and print its answer as JSON. Leaves: `mine`, `get`, `update`, `set-redirect-uris`, `asks`, `set-scopes`, `set-requires`, `set-run-notice-url`, `keys list|add|retire|delete|set-jwks-uri|remove-jwks-uri`, `testers list|add|remove`. `--app` defaults to `CROUTER_CLIENT_ID` in `local/app.env`; `keys add` takes `--key-file <path>` and sends only the public half. Deleting an app, its marketplace listing, spend cap, sharing and provider role are console-only. | No |
 
 ## Pages
 

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.479";
+export declare const SDK_VERSION = "0.3.481";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.479';
+export const SDK_VERSION = '0.3.481';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/dist/whoami-command.d.ts

@@ -0,0 +1 @@
+export declare function runWhoami(argv: string[]): Promise<number>;

package/dist/whoami-command.js

@@ -0,0 +1,30 @@
+import { updateEntry } from './credentials.js';
+import { usageOf } from './cli-usage.js';
+import { NOT_LOGGED_IN, openSession, parseFlags, reportFailure, resolveIssuer } from './developer-common.js';
+export async function runWhoami(argv) {
+    let flags;
+    try {
+        flags = parseFlags(argv.slice(1), { value: ['--issuer'] }, usageOf('whoami'));
+        if (flags.rest.length)
+            throw new Error(usageOf('whoami'));
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const issuer = resolveIssuer(flags.values.get('--issuer'));
+    try {
+        const session = await openSession(issuer, NOT_LOGGED_IN, async () => { await updateEntry(issuer, () => undefined); });
+        if (!session)
+            return 1;
+        const { token, entry } = session;
+        console.log([
+            `${token.account.display} (${token.account.id}) on ${issuer}`,
+            `Login ${entry.name ?? token.credential_id}, expires ${token.expires_at.slice(0, 10)} or after 14 days unused.`,
+        ].join('\n'));
+        return 0;
+    }
+    catch (error) {
+        return reportFailure(error);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.479",
+  "version": "0.3.481",
   "crouterContract": "1.7",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
@@ -44,8 +44,8 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.479",
-    "@north-light/identity": "0.3.479",
+    "@north-light/api": "0.3.481",
+    "@north-light/identity": "0.3.481",
     "jose": "^6.2.1"
   },
   "peerDependencies": {