@north-light/api 0.3.580 → 0.3.588

package/dist/core/scopes.js

@@ -0,0 +1,48 @@
+import { parseScope } from '@north-light/identity';
+import { scopeAllowed } from '../shared/env.js';
+import { InputError } from './io.js';
+export { scopeAllowed };
+/** The scopes an unrestricted local terminal run presents to the document substrate. */
+export const SCOPE_VOCABULARY = [
+    'crtr:llm', 'crtr:act', 'crtr:schedule', 'crtr:memory:rw:user',
+    'crtr:memory:manage:user', 'crtr:files:rw:user:.',
+];
+/** A memory string naming the app itself (`crtr:memory:read|rw:app:<A>`, or its profile form). No grant holds one: it exists only to
+ *  narrow a run within its own space. */
+export function isOwnMemoryScope(scope, grantee) {
+    const parts = scope.split(':');
+    return parts[0] === 'crtr' && parts[1] === 'memory' && (parts[2] === 'read' || parts[2] === 'rw') && `${parts[3]}:${parts[4]}` === grantee;
+}
+/** Reject unknown scope strings before they can silently change an allow-list. */
+export function validateScopes(value) {
+    if (!Array.isArray(value))
+        throw new InputError({ error: 'unknown_scope', message: 'scopes must be a list', received: value, field: 'scopes', next: 'Pass identity scope strings.' });
+    for (const scope of value) {
+        try {
+            if (typeof scope !== 'string')
+                throw new TypeError('scope is not a string');
+            parseScope(scope);
+        }
+        catch {
+            throw new InputError({ error: 'unknown_scope', message: `unknown scope: ${String(scope)}`, received: scope, field: 'scopes', next: 'Pass identity scope strings.' });
+        }
+    }
+    return [...value];
+}
+export function assertScope(meta, scope) {
+    if (scopeAllowed(meta.scopes, scope))
+        return;
+    throw new ScopeDeniedError(`node ${meta.node_id}`, scope);
+}
+/** `holder` names who lacks the scope in prose — `node <id>` for a node's own
+ *  allow-list, `the bearer token` for a scoped API token's ceiling. */
+export class ScopeDeniedError extends Error {
+    holder;
+    scope;
+    constructor(holder, scope) {
+        super(`${holder} does not hold the ${scope} scope`);
+        this.holder = holder;
+        this.scope = scope;
+        this.name = 'ScopeDeniedError';
+    }
+}

package/dist/core/secrets/env-rows.d.ts

@@ -0,0 +1,18 @@
+import { type CanvasDb } from '../canvas/db.js';
+import { type SecretsKey } from './index.js';
+export type EnvOwnerKind = 'profile' | 'app' | 'deployment';
+export interface EnvOwner {
+    person: string | null;
+    kind: EnvOwnerKind;
+    id: string;
+}
+export declare const aadOf: (owner: EnvOwner, name: string) => string;
+/** Insert or replace one value. Returns true when the name was new. */
+export declare function putEnvRow(owner: EnvOwner, name: string, value: string, key?: SecretsKey): Promise<boolean>;
+/** Seal one value into an open transaction, keeping a row that already holds the name. Used by the one-time boot copy. */
+export declare function putEnvRowIfAbsent(db: CanvasDb, owner: EnvOwner, name: string, value: string, key?: SecretsKey): Promise<void>;
+export declare function removeEnvRow(owner: EnvOwner, name: string): Promise<boolean>;
+/** Names only: no value is opened. */
+export declare function listEnvRowNames(owner: EnvOwner): Promise<string[]>;
+/** Every value of one owner, opened. Throws `SecretsError` when any row fails to open: a wrong key never yields an empty or partial map. */
+export declare function readEnvRows(owner: EnvOwner, key?: SecretsKey): Promise<Record<string, string>>;

package/dist/core/secrets/env-rows.js

@@ -0,0 +1,40 @@
+// Sealed `env_vars` rows (design-fleet D81): one table for profile, app and deployment variables.
+// Values are sealed under the control-plane key with the row's identity as additional data, never returned by a route,
+// and opened only by the readers here. Reserved names (`CRTR_*`, `HOME`) are refused at write by the stores that call this.
+import { openDb } from '../canvas/db.js';
+import { loadSecretsKey, open, seal } from './index.js';
+export const aadOf = (owner, name) => `env_vars|${owner.person ?? ''}|${owner.kind}|${owner.id}|${name}`;
+const personKey = (owner) => owner.person ?? '';
+/** Insert or replace one value. Returns true when the name was new. */
+export async function putEnvRow(owner, name, value, key = loadSecretsKey()) {
+    const { sealed, keyId } = seal(value, key, aadOf(owner, name));
+    const db = await openDb();
+    const row = await db.prepare(`INSERT INTO env_vars (person, owner_kind, owner_id, name, value_sealed, key_id, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (COALESCE(person, ''), owner_kind, owner_id, name) DO UPDATE SET value_sealed = EXCLUDED.value_sealed, key_id = EXCLUDED.key_id, updated_at = EXCLUDED.updated_at
+    RETURNING (xmax = 0) AS created`).get(owner.person, owner.kind, owner.id, name, sealed, keyId, new Date().toISOString());
+    return row.created;
+}
+/** Seal one value into an open transaction, keeping a row that already holds the name. Used by the one-time boot copy. */
+export async function putEnvRowIfAbsent(db, owner, name, value, key = loadSecretsKey()) {
+    const { sealed, keyId } = seal(value, key, aadOf(owner, name));
+    await db.prepare(`INSERT INTO env_vars (person, owner_kind, owner_id, name, value_sealed, key_id, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (COALESCE(person, ''), owner_kind, owner_id, name) DO NOTHING`).run(owner.person, owner.kind, owner.id, name, sealed, keyId, new Date().toISOString());
+}
+export async function removeEnvRow(owner, name) {
+    const result = await (await openDb()).prepare(`DELETE FROM env_vars WHERE COALESCE(person, '') = ? AND owner_kind = ? AND owner_id = ? AND name = ?`).run(personKey(owner), owner.kind, owner.id, name);
+    return result.changes > 0;
+}
+/** Names only: no value is opened. */
+export async function listEnvRowNames(owner) {
+    const rows = await (await openDb()).prepare(`SELECT name FROM env_vars WHERE COALESCE(person, '') = ? AND owner_kind = ? AND owner_id = ? ORDER BY name`).all(personKey(owner), owner.kind, owner.id);
+    return rows.map((r) => r.name);
+}
+/** Every value of one owner, opened. Throws `SecretsError` when any row fails to open: a wrong key never yields an empty or partial map. */
+export async function readEnvRows(owner, key = loadSecretsKey()) {
+    const rows = await (await openDb()).prepare(`SELECT name, value_sealed, key_id FROM env_vars WHERE COALESCE(person, '') = ? AND owner_kind = ? AND owner_id = ?`)
+        .all(personKey(owner), owner.kind, owner.id);
+    const out = Object.create(null);
+    for (const row of rows)
+        out[row.name] = open(row.value_sealed, row.key_id, key, aadOf(owner, row.name));
+    return out;
+}

package/dist/core/secrets/environment-owner.d.ts

@@ -0,0 +1,8 @@
+/** The profile that owns `environmentId` (an environment object whose owner carries a `profile` identity), or null when an app owns it. */
+export declare function environmentOwnerProfile(environmentId: string): Promise<string | null>;
+/** Whether profile `profileId` belongs to `app`; a profile of another app adds no secrets. */
+export declare function profileInApp(profileId: string, app: string): Promise<boolean>;
+/** The secrets a local process, bash command or cron of `app` under `profileId` receives: the app's rows, then the rows of the profile that owns the
+ *  profile's environment (a profile pointing at another profile's environment gets that profile's, not its own), plus the deployment rows.
+ *  A profile on the machine environment (owned by the app, not a profile) is its own owner. */
+export declare function localEnvironmentSecrets(profileId: string | null, app: string): Promise<Record<string, string>>;

package/dist/core/secrets/environment-owner.js

@@ -0,0 +1,31 @@
+// Which profile owns a node's environment, and the secrets of that environment on a process that runs on this host.
+// Blaxel's launch context uses `environmentOwnerProfile` for the same owner, so one rule holds on every path (design-fleet, Environment secrets resolution).
+import { openDb } from '../canvas/db.js';
+import { personIdAsync } from '../canvas/person.js';
+import { environmentSecrets } from './environment-secrets.js';
+/** The profile that owns `environmentId` (an environment object whose owner carries a `profile` identity), or null when an app owns it. */
+export async function environmentOwnerProfile(environmentId) {
+    const owner = await (await openDb()).prepare(`SELECT i.external_id AS profile FROM objects o JOIN identities i ON i.object = o.owner AND i.scheme = 'profile' WHERE o.id = ?`).get(environmentId);
+    return owner?.profile ?? null;
+}
+/** Whether profile `profileId` belongs to `app`; a profile of another app adds no secrets. */
+export async function profileInApp(profileId, app) {
+    const row = await (await openDb()).prepare('SELECT grantee FROM profiles WHERE id = ?').get(profileId);
+    return (row?.grantee ?? 'app:terminal') === app;
+}
+/** The secrets a local process, bash command or cron of `app` under `profileId` receives: the app's rows, then the rows of the profile that owns the
+ *  profile's environment (a profile pointing at another profile's environment gets that profile's, not its own), plus the deployment rows.
+ *  A profile on the machine environment (owned by the app, not a profile) is its own owner. */
+export async function localEnvironmentSecrets(profileId, app) {
+    let person = await personIdAsync();
+    let ownerProfile = null;
+    if (profileId !== null && profileId !== '') {
+        const row = await (await openDb()).prepare('SELECT person, environment_id FROM profiles WHERE id = ?').get(profileId);
+        if (row !== undefined)
+            person = row.person;
+        // On the machine environment (an app owns it) a profile's own rows are its secrets; a profile pointing at another environment gets that environment's owner's.
+        const machine = row?.environment_id == null || (await (await openDb()).prepare('SELECT kind FROM environments WHERE object = ?').get(row.environment_id))?.kind === 'machine';
+        ownerProfile = machine ? profileId : await environmentOwnerProfile(row.environment_id);
+    }
+    return environmentSecrets({ person, app, ownerProfile, ownerProfileInApp: ownerProfile !== null && await profileInApp(ownerProfile, app), includeDeployment: true });
+}

package/dist/core/secrets/environment-secrets.d.ts

@@ -0,0 +1,14 @@
+import type { SecretsKey } from './index.js';
+/** `owner_id` of every deployment row. */
+export declare const DEPLOYMENT_ID = "_deployment";
+export interface EnvironmentSecretsInput {
+    person: string;
+    app: string;
+    /** The environment's owning profile, or null when the owner is the app. */
+    ownerProfile: string | null;
+    /** Whether that profile's grantee is `app`; a profile of another app adds nothing. */
+    ownerProfileInApp: boolean;
+    includeDeployment: boolean;
+    key?: SecretsKey;
+}
+export declare function environmentSecrets(input: EnvironmentSecretsInput): Promise<Record<string, string>>;

package/dist/core/secrets/environment-secrets.js

@@ -0,0 +1,14 @@
+// Environment secrets resolution (design-fleet): one merge order for the process runner, the Blaxel runner, the bash handler and cron.
+// Rows (person, app, A), then — when the owning profile belongs to app A — rows (person, profile, O) over them.
+// Deployment rows (person null) are included only when `includeDeployment` is set (the process runner), never for a sandbox.
+import { readEnvRows } from './env-rows.js';
+/** `owner_id` of every deployment row. */
+export const DEPLOYMENT_ID = '_deployment';
+export async function environmentSecrets(input) {
+    const { person, app, key } = input;
+    return {
+        ...await readEnvRows({ person, kind: 'app', id: app }, key),
+        ...(input.includeDeployment ? await readEnvRows({ person: null, kind: 'deployment', id: DEPLOYMENT_ID }, key) : {}),
+        ...(input.ownerProfile !== null && input.ownerProfileInApp ? await readEnvRows({ person, kind: 'profile', id: input.ownerProfile }, key) : {}),
+    };
+}

package/dist/core/secrets/index.d.ts

@@ -0,0 +1,2 @@
+export { SecretsError, keyIdOf, open, parseSecretsKey, seal, type Sealed, type SecretsKey } from './seal.js';
+export { loadSecretsKey, secretsKeyFile } from './key.js';

package/dist/core/secrets/index.js

@@ -0,0 +1,2 @@
+export { SecretsError, keyIdOf, open, parseSecretsKey, seal } from './seal.js';
+export { loadSecretsKey, secretsKeyFile } from './key.js';

package/dist/core/secrets/key.d.ts

@@ -0,0 +1,3 @@
+import { type SecretsKey } from './seal.js';
+export declare const secretsKeyFile: () => string;
+export declare function loadSecretsKey(): SecretsKey;

package/dist/core/secrets/key.js

@@ -0,0 +1,33 @@
+// The control plane's secrets key. The only reader of `CRTR_SECRETS_KEY` and `<runtime>/secrets/secrets.key` (D80).
+// Cloud: the env var, never a file. A Mac: a 0600 key file created at first use.
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { secretsDir } from '../layout.js';
+import { ensureDir } from '../fs-utils.js';
+import { parseSecretsKey, SecretsError } from './seal.js';
+const KEY_ENV = 'CRTR_SECRETS_KEY';
+export const secretsKeyFile = () => join(secretsDir(), 'secrets.key');
+/** A process pointed at a shared database (`CRTR_DATABASE_URL`) is a cloud role and must be given the key; it never invents one. */
+const isCloudProcess = () => (process.env['CRTR_DATABASE_URL'] ?? '') !== '';
+let cached;
+export function loadSecretsKey() {
+    const fromEnv = process.env[KEY_ENV];
+    if (fromEnv !== undefined && fromEnv !== '') {
+        if (cached?.source !== `env:${fromEnv}`)
+            cached = { source: `env:${fromEnv}`, key: parseSecretsKey(fromEnv) };
+        return cached.key;
+    }
+    if (isCloudProcess())
+        throw new SecretsError('secrets_key_missing', `${KEY_ENV} is not set; a cloud process cannot seal or open secrets without it`);
+    const path = secretsKeyFile();
+    if (cached?.source !== `file:${path}`) {
+        if (!existsSync(path)) {
+            ensureDir(join(path, '..'));
+            writeFileSync(path, `${randomBytes(32).toString('hex')}\n`, { mode: 0o600, flag: 'wx' });
+        }
+        chmodSync(path, 0o600);
+        cached = { source: `file:${path}`, key: parseSecretsKey(readFileSync(path, 'utf8')) };
+    }
+    return cached.key;
+}

package/dist/core/secrets/seal.d.ts

@@ -0,0 +1,18 @@
+export declare class SecretsError extends Error {
+    readonly code: 'secrets_key_missing' | 'secrets_key_invalid' | 'secrets_open_failed';
+    constructor(code: SecretsError['code'], message: string);
+}
+export interface SecretsKey {
+    id: string;
+    key: Buffer;
+}
+export interface Sealed {
+    sealed: Buffer;
+    keyId: string;
+}
+/** The id a key is known by in `key_id` columns: a prefix of its SHA-256, never reversible to the key. */
+export declare function keyIdOf(key: Buffer): string;
+/** Parse a 32-byte key written as 64 hex characters or as base64. */
+export declare function parseSecretsKey(text: string): SecretsKey;
+export declare function seal(plaintext: string, key: SecretsKey, aad: string): Sealed;
+export declare function open(sealed: Buffer | Uint8Array, keyId: string, key: SecretsKey, aad: string): string;

package/dist/core/secrets/seal.js

@@ -0,0 +1,43 @@
+// Seal and open secret columns (design-fleet D80): AES-256-GCM under one control-plane key, `key_id` per value.
+// A sealed value is `iv(12) | tag(16) | ciphertext`. `aad` binds a value to its row (person, owner, name), so a sealed
+// value copied onto another row fails to open. Opening never returns an empty or partial value: any mismatch throws.
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+export class SecretsError extends Error {
+    code;
+    constructor(code, message) { super(message); this.name = 'SecretsError'; this.code = code; }
+}
+/** The id a key is known by in `key_id` columns: a prefix of its SHA-256, never reversible to the key. */
+export function keyIdOf(key) { return createHash('sha256').update(key).digest('hex').slice(0, 16); }
+/** Parse a 32-byte key written as 64 hex characters or as base64. */
+export function parseSecretsKey(text) {
+    const trimmed = text.trim();
+    const key = /^[0-9a-fA-F]{64}$/.test(trimmed) ? Buffer.from(trimmed, 'hex') : Buffer.from(trimmed, 'base64');
+    if (key.length !== 32)
+        throw new SecretsError('secrets_key_invalid', 'the secrets key must be 32 bytes (64 hex characters or base64)');
+    return { id: keyIdOf(key), key };
+}
+export function seal(plaintext, key, aad) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key.key, iv);
+    cipher.setAAD(Buffer.from(aad, 'utf8'));
+    const body = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    return { sealed: Buffer.concat([iv, cipher.getAuthTag(), body]), keyId: key.id };
+}
+export function open(sealed, keyId, key, aad) {
+    if (keyId !== key.id)
+        throw new SecretsError('secrets_open_failed', `sealed value was written under key ${keyId}, this process holds key ${key.id}`);
+    const bytes = Buffer.from(sealed);
+    if (bytes.length < IV_BYTES + TAG_BYTES)
+        throw new SecretsError('secrets_open_failed', 'sealed value is truncated');
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key.key, bytes.subarray(0, IV_BYTES));
+        decipher.setAAD(Buffer.from(aad, 'utf8'));
+        decipher.setAuthTag(bytes.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+        return Buffer.concat([decipher.update(bytes.subarray(IV_BYTES + TAG_BYTES)), decipher.final()]).toString('utf8');
+    }
+    catch {
+        throw new SecretsError('secrets_open_failed', 'sealed value failed authentication (wrong key, altered bytes or another row)');
+    }
+}

package/dist/core/secrets.d.ts

@@ -0,0 +1,50 @@
+import type { Scope } from '../types.js';
+/** The 0600 secrets store: raw relay/bearer tokens for `remoteCanvas.targets`,
+ *  kept OUT of `config.json` (which is not permission-hardened and is treated
+ *  as shareable/inspectable) and never logged. `crtr canvas config add
+ *  --relay-token -` is the ONLY accepted form — reads the raw token from
+ *  stdin; any other value is rejected with a generic error (never echoing
+ *  what was received). Keyed by `RemoteCanvasTarget.relayTokenRef`, never by
+ *  the target name directly, so a rename doesn't orphan the secret. */
+export interface SecretsStore {
+    relayTokens: Record<string, string>;
+    apiToken?: string;
+    scopedApiTokens?: ScopedApiToken[];
+}
+/** A bearer token minted by `crtr sys connect --scopes` whose `scopes` list is
+ *  the ceiling for every scope-gated daemon operation the holder performs. The
+ *  owner token (`apiToken`) has no ceiling. */
+export interface ScopedApiToken {
+    token: string;
+    grantee: string;
+    scopes: string[];
+    created: string;
+}
+export declare function readSecrets(scope: Scope): SecretsStore;
+/** Replaces secrets.json whole (temp file, fsync, rename, directory fsync) at mode 0600 -- forced even
+ *  over a pre-existing looser file, e.g. one hand-copied from another machine -- so a killed VM or a
+ *  volume handoff never leaves the relay tokens empty or partial. */
+export declare function writeSecrets(scope: Scope, store: SecretsStore): void;
+export declare function getRelayToken(ref: string, scope: Scope): string | undefined;
+export declare function setRelayToken(ref: string, token: string, scope: Scope): void;
+export declare function deleteRelayToken(ref: string, scope: Scope): void;
+export declare function getApiToken(scope: Scope): string | undefined;
+export declare function setApiToken(token: string, scope: Scope): void;
+export declare function listScopedApiTokens(scope: Scope): ScopedApiToken[];
+export declare function addScopedApiToken(entry: ScopedApiToken, scope: Scope): void;
+/** The `crtr_app_` token minted for an installed plugin, if it holds one. */
+export declare function pluginAppToken(plugin: string): ScopedApiToken | undefined;
+/** Mint the plugin's `crtr_app_` token when absent; rewrite its `scopes` in place (same token) when they
+ *  differ; otherwise write nothing. */
+export declare function ensurePluginAppToken(plugin: string, scopes: readonly string[]): ScopedApiToken;
+/** Remove the plugin's `crtr_app_` tokens. Entries minted by `crtr sys connect` are never touched. */
+export declare function revokePluginAppTokens(plugin: string): boolean;
+/** Look a raw scoped bearer up in the user store. Cached; the cache is dropped by every in-process
+ *  `writeSecrets` and re-read when the file's (inode, size, mtime) changes, so a revocation by any
+ *  process, including an atomic replace that keeps the mtime, is seen on the next lookup. */
+export declare function findScopedApiToken(token: string): ScopedApiToken | undefined;
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export declare function fingerprint(token: string): string;

package/dist/core/secrets.js

@@ -0,0 +1,147 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { scopeRoot, requireScopeRoot, userScopeRoot } from './scope.js';
+import { secretsDir } from './layout.js';
+import { atomicWriteJson, ensureDir } from './fs-utils.js';
+const SECRETS_FILE = 'secrets.json';
+function secretsPathFor(root) {
+    return join(root === userScopeRoot() ? secretsDir() : root, SECRETS_FILE);
+}
+export function readSecrets(scope) {
+    const root = scopeRoot(scope);
+    if (!root)
+        return { relayTokens: {} };
+    const p = secretsPathFor(root);
+    if (!existsSync(p))
+        return { relayTokens: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        const scoped = Array.isArray(parsed.scopedApiTokens)
+            ? parsed.scopedApiTokens.filter((t) => typeof t?.token === 'string' && t.token !== '' && typeof t.grantee === 'string' && /^app:[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(t.grantee) && Array.isArray(t.scopes) && typeof t.created === 'string')
+            : [];
+        return {
+            relayTokens: parsed.relayTokens ?? {},
+            ...(typeof parsed.apiToken === 'string' && parsed.apiToken !== '' ? { apiToken: parsed.apiToken } : {}),
+            ...(scoped.length > 0 ? { scopedApiTokens: scoped } : {}),
+        };
+    }
+    catch {
+        return { relayTokens: {} };
+    }
+}
+/** Replaces secrets.json whole (temp file, fsync, rename, directory fsync) at mode 0600 -- forced even
+ *  over a pre-existing looser file, e.g. one hand-copied from another machine -- so a killed VM or a
+ *  volume handoff never leaves the relay tokens empty or partial. */
+export function writeSecrets(scope, store) {
+    const root = requireScopeRoot(scope);
+    const p = secretsPathFor(root);
+    ensureDir(root === userScopeRoot() ? secretsDir() : root);
+    atomicWriteJson(p, store, { mode: 0o600, durable: true });
+    scopedLookup = undefined;
+}
+export function getRelayToken(ref, scope) {
+    return readSecrets(scope).relayTokens[ref];
+}
+export function setRelayToken(ref, token, scope) {
+    const s = readSecrets(scope);
+    s.relayTokens[ref] = token;
+    writeSecrets(scope, s);
+}
+export function deleteRelayToken(ref, scope) {
+    const s = readSecrets(scope);
+    delete s.relayTokens[ref];
+    writeSecrets(scope, s);
+}
+export function getApiToken(scope) {
+    return readSecrets(scope).apiToken;
+}
+export function setApiToken(token, scope) {
+    const s = readSecrets(scope);
+    s.apiToken = token;
+    writeSecrets(scope, s);
+}
+export function listScopedApiTokens(scope) {
+    return readSecrets(scope).scopedApiTokens ?? [];
+}
+export function addScopedApiToken(entry, scope) {
+    const s = readSecrets(scope);
+    s.scopedApiTokens = [...(s.scopedApiTokens ?? []), entry];
+    writeSecrets(scope, s);
+}
+const GRANTEE = /^app:[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const APP_TOKEN_PREFIX = 'crtr_app_';
+function appGrantee(plugin) {
+    const grantee = `app:${plugin}`;
+    if (!GRANTEE.test(grantee))
+        throw new Error(`invalid plugin name for an app token: ${JSON.stringify(plugin)}`);
+    return grantee;
+}
+const isAppEntry = (t) => t.token.startsWith(APP_TOKEN_PREFIX);
+/** The `crtr_app_` token minted for an installed plugin, if it holds one. */
+export function pluginAppToken(plugin) {
+    const grantee = appGrantee(plugin);
+    return listScopedApiTokens('user').find((t) => t.grantee === grantee && isAppEntry(t));
+}
+/** Mint the plugin's `crtr_app_` token when absent; rewrite its `scopes` in place (same token) when they
+ *  differ; otherwise write nothing. */
+export function ensurePluginAppToken(plugin, scopes) {
+    const grantee = appGrantee(plugin);
+    const store = readSecrets('user');
+    const all = store.scopedApiTokens ?? [];
+    const existing = all.find((t) => t.grantee === grantee && isAppEntry(t));
+    const want = [...scopes];
+    if (existing && existing.scopes.length === want.length && existing.scopes.every((x, i) => x === want[i]))
+        return existing;
+    const next = existing
+        ? { ...existing, scopes: want }
+        : { token: `${APP_TOKEN_PREFIX}${randomBytes(32).toString('base64url')}`, grantee, scopes: want, created: new Date().toISOString() };
+    store.scopedApiTokens = existing ? all.map((t) => (t === existing ? next : t)) : [...all, next];
+    writeSecrets('user', store);
+    return next;
+}
+/** Remove the plugin's `crtr_app_` tokens. Entries minted by `crtr sys connect` are never touched. */
+export function revokePluginAppTokens(plugin) {
+    const grantee = appGrantee(plugin);
+    const store = readSecrets('user');
+    const all = store.scopedApiTokens ?? [];
+    const kept = all.filter((t) => !(t.grantee === grantee && isAppEntry(t)));
+    if (kept.length === all.length)
+        return false;
+    if (kept.length > 0)
+        store.scopedApiTokens = kept;
+    else
+        delete store.scopedApiTokens;
+    writeSecrets('user', store);
+    return true;
+}
+let scopedLookup;
+function secretsFileKey() {
+    const root = scopeRoot('user');
+    if (!root)
+        return 'none';
+    try {
+        const st = statSync(secretsPathFor(root), { bigint: true });
+        return `${st.ino}:${st.size}:${st.mtimeNs}`;
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** Look a raw scoped bearer up in the user store. Cached; the cache is dropped by every in-process
+ *  `writeSecrets` and re-read when the file's (inode, size, mtime) changes, so a revocation by any
+ *  process, including an atomic replace that keeps the mtime, is seen on the next lookup. */
+export function findScopedApiToken(token) {
+    const key = secretsFileKey();
+    if (!scopedLookup || scopedLookup.key !== key) {
+        scopedLookup = { key, byToken: new Map(listScopedApiTokens('user').map((t) => [t.token, t])) };
+    }
+    return scopedLookup.byToken.get(token);
+}
+/** A short, non-reversible display fingerprint of a raw token — safe to print
+ *  in `canvas config list`/`show` output. NEVER derive this from anything
+ *  that could round-trip back to the token, and never log/return the raw
+ *  token itself alongside it. */
+export function fingerprint(token) {
+    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+}

package/dist/core/self-update.d.ts

@@ -0,0 +1,27 @@
+export declare const SELF_UPDATE_SCRIPT: string;
+export declare function currentVersion(): string;
+export declare function selfUpdate(): void;
+export interface SelfCheckResult {
+    current: string;
+    latest: string;
+    /** The npm package an update installs from: this install's own name, or
+     *  `@north-light/cli` for an install of the deprecated `@crouter/cli`. */
+    package: string;
+    /** True when an update moves this install to a different package. */
+    migrating: boolean;
+}
+/** Check whether a newer crtr version is available on npm. The package to ask
+ *  comes from scripts/self-update.mjs, so a check and an update always agree.
+ *  Returns null when npm is unreachable. */
+export declare function selfCheck(): SelfCheckResult | null;
+export interface ContentUpdateEntry {
+    name: string;
+    kind: 'marketplace' | 'plugin';
+    current: string | null;
+    latest: string | null;
+    up_to_date: boolean;
+    unreachable: boolean;
+}
+/** Check whether any marketplace/plugin has updates available.
+ *  Returns per-item status without applying anything. */
+export declare function contentCheck(): ContentUpdateEntry[];

package/dist/core/self-update.js

@@ -0,0 +1,77 @@
+// Self-update and content-check primitives. They live in core/ so auto-update.ts
+// (core) reaches them without importing commands/update.ts, which would invert
+// the core→commands layering.
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { listAllPlugins, listAllMarketplaces } from './resolver.js';
+import { crtrVersion } from '../shared/crtr-version.js';
+import { fetch, currentSha, remoteSha } from './git.js';
+import { general } from './errors.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// src/core/self-update.ts → up to src/ → up to pkg root
+const PKG_ROOT = join(__dirname, '..', '..');
+export const SELF_UPDATE_SCRIPT = join(PKG_ROOT, 'scripts', 'self-update.mjs');
+export function currentVersion() {
+    return crtrVersion();
+}
+export function selfUpdate() {
+    const res = spawnSync(process.execPath, [SELF_UPDATE_SCRIPT], { stdio: 'inherit' });
+    if (res.error)
+        throw general(`self-update failed: ${res.error.message}`);
+    if (res.status !== 0)
+        throw general(`self-update failed (${res.status ?? res.signal ?? 'unknown'})`);
+}
+/** Check whether a newer crtr version is available on npm. The package to ask
+ *  comes from scripts/self-update.mjs, so a check and an update always agree.
+ *  Returns null when npm is unreachable. */
+export function selfCheck() {
+    const res = spawnSync(process.execPath, [SELF_UPDATE_SCRIPT, '--resolve'], { encoding: 'utf8' });
+    if (res.status !== 0)
+        return null;
+    try {
+        const parsed = JSON.parse(res.stdout);
+        if (typeof parsed.latest !== 'string')
+            return null;
+        return { current: currentVersion(), latest: parsed.latest, package: parsed.package, migrating: parsed.migrating };
+    }
+    catch {
+        return null;
+    }
+}
+/** Check whether any marketplace/plugin has updates available.
+ *  Returns per-item status without applying anything. */
+export function contentCheck() {
+    const results = [];
+    const marketplaces = listAllMarketplaces();
+    for (const mkt of marketplaces) {
+        const fetchRes = fetch(mkt.root, mkt.ref);
+        if (fetchRes.status !== 0) {
+            results.push({ name: mkt.name, kind: 'marketplace', current: null, latest: null, up_to_date: true, unreachable: true });
+            continue;
+        }
+        const head = currentSha(mkt.root);
+        const remote = remoteSha(mkt.root, mkt.ref);
+        const up_to_date = head !== null && remote !== null ? head === remote : true;
+        results.push({ name: mkt.name, kind: 'marketplace', current: head, latest: remote, up_to_date, unreachable: false });
+    }
+    const plugins = listAllPlugins();
+    for (const plugin of plugins) {
+        if (!plugin.enabled)
+            continue;
+        if (plugin.sourceMarketplace)
+            continue;
+        const ref = 'main';
+        const fetchRes = fetch(plugin.root, ref);
+        if (fetchRes.status !== 0) {
+            results.push({ name: plugin.name, kind: 'plugin', current: null, latest: null, up_to_date: true, unreachable: true });
+            continue;
+        }
+        const head = currentSha(plugin.root);
+        const remote = remoteSha(plugin.root, ref);
+        const up_to_date = head !== null && remote !== null ? head === remote : true;
+        results.push({ name: plugin.name, kind: 'plugin', current: head, latest: remote, up_to_date, unreachable: false });
+    }
+    return results;
+}