@north-light/cli 0.3.482 → 0.3.484

package/dist/builtin-memory/crouter-sdk/release-notes.md

@@ -9,6 +9,85 @@ when-and-why-to-read: When you need Release notes, this knowledge should be read
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.484
+
+Plugins can now declare canvas object kinds and act on the canvas, and an app token can be granted canvas scopes. Everything below is additive: no request or response an existing app sends or reads changes, with one runtime-side exception under [Unknown bearers](#unknown-bearers-are-refused).
+
+### Plugin manifests declare `object_kinds` and `scopes` (additive)
+
+`plugin.json` and `bundle.json` take two optional top-level blocks. `object_kinds` maps a kind name (`<plugin>.<name>`, so the first segment is the plugin's own name) to `{ description, events, read? }`: `events` holds up to 64 entries `{ level: 1-10, supersedes?: boolean }`, and `read.command` is a leaf path below the plugin's root command. That leaf must answer once: a leaf declared `rest.streaming: true` is refused as a `read.command`. `scopes` lists the canvas scopes the plugin asks for. A provider bundle may not declare `scopes`: a cloud app's scopes come from directory consent. Install, update and enable refuse an invalid block and keep the installed version; a kind another owner already holds is reported as `kind_owned` and the plugin's other kinds still apply. `crtr pkg plugin install|update|enable` print these as `warnings`, plus `appScopes` (the scopes the plugin's token now carries). Plugin authors: see [[crouter-plugin/deploying]].
+
+`ReconcilePackagesDTO` (the answer of `POST /v1/documents/reconcile-packages`) gains two optional fields: `kinds` (`applied` with `outcome` of `inserted`, `updated` or `unchanged`; `refused` with code `kind_owned`; `invalid` plugins with the reason) and `tokens` (`granted` plugins with their scopes, and `revoked` plugin names).
+
+### Canvas object scopes `crtr:objects:<verb>:<target>` (additive)
+
+`@north-light/identity` accepts `crtr:objects:<read|watch|link|write>:<user|node|profile:<id>|app:<x>>`. Each scope is its own grant: `covers` is exact equality, so `crtr:objects:write:user` does not imply `read`. The target is where the object lives:
+
+- `user`: objects in the person's space.
+- `profile:<id>`: objects below that profile.
+- `app:<x>`: nodes and custom objects of another app `x`. An app never needs a scope for its own objects, and a plugin may not declare its own `app:<plugin>` space.
+- `node`: any node, including the stub of a node on another of the account's machines.
+
+`read` lets the holder read objects of the target, `write` change them, and `link` (below) make a node watch an object the holder owns. `watch` lets a custom object that watches an object of the target read it. Holding a scope never lifts run confinement inside the owning app, and a revoked grant holds nothing. A public custom object is readable by any app that may use the owning app's tools, with no scope. The app listener now serves the canvas operations (`objects.*`, `custom-objects.*`, `docs.*`) to an app grant token under its resolved scopes; those rows answered `unknown operation` there before.
+
+### The `crtr_app_` credential and its socket fetch (additive)
+
+Each enabled local plugin that declares `object_kinds` or `scopes`, or serves over HTTP, holds one `crtr_app_…` token carrying its manifest's `scopes`. It is issued when the plugin is installed or enabled, reissued on update (the scopes can change), and revoked on uninstall or disable. crtrd accepts it as a bearer on its unix socket and TCP listener, looks it up on every request (a revoked token stops working on the next one), and treats the holder as app `app:<plugin>`.
+
+- `GET /v1/plugins/:name/app-token` (new operation `plugins.app-token`, person and broker callers) answers `{ token, socket }`, or `404 not_found` when the plugin is not installed, enabled, valid and holding a token. A service fetches it once at startup over the socket as the user who runs it. A node whose uid is not the daemon's gets `403 forbidden`.
+- An exec plugin receives the token as `CRTR_APP_TOKEN` and the socket as `CRTR_DAEMON_SOCKET` in its leaf's environment. crtr never sends the token to a plugin's HTTP port.
+- SDK: `CrtrClient.plugins.appToken(name)` and the DTO `PluginAppTokenDTO`; route helper `routes.pluginAppToken(name)`.
+
+### `Crtr-Caller` and `Crtr-Signature` on local HTTP calls (additive)
+
+Every HTTP call to a plugin carries `Crtr-Caller: node=<id>; machine=<id>; profile=<id>; run=<id>` (fields in that order, empty ones left out, header omitted when none). Calls to a local plugin's endpoint origin also carry `Crtr-Signature: v1,t=<unix seconds>,h=<signed header names>,sig=<base64url HMAC-SHA256 keyed by the plugin's token>` plus a fresh `Crtr-Request-Id`. A manifest cannot set these three header names. Provider calls carry `Crtr-Caller` too. Plugin authors: the canonical string and a reference verifier are in [[crouter-plugin/deploying]].
+
+crtrd signs the call; the CLI never holds the token. `POST /v1/plugins/:name/call-headers` (new operation `plugins.call-headers`, person and broker callers) takes only digests, `{ method, url, body_sha256, header_names, headers_sha256 }`, and answers `{ headers }` (`Crtr-Caller`, and `Crtr-Signature` when the URL is on the installed endpoint's origin and that endpoint is loopback). Any other URL gets `Crtr-Caller` only. An unknown or disabled plugin and a provider plugin answer `404 not_found`; malformed digests answer `400 invalid_request`. SDK: `CrtrClient.plugins.callHeaders(name, request)`, `PluginCallHeadersRequestDTO`, `PluginCallHeadersDTO`, `routes.pluginCallHeaders(name)`.
+
+### Unknown bearers are refused
+
+A bearer that crtrd does not recognize is now `401` on the TCP listener as well. A runtime with no owner token used to treat a request with a bearer it did not know as the owner; now only a request with no bearer is, and a live `crtr_app_` token is that app. `crtr_pub_` and the owner token behave as before.
+
+### `custom-objects.register` takes `privacy`, and `events` is optional (additive)
+
+`RegisterCustomObjectRequestDTO.privacy?` is `public` (the default), `friends` or `private`; setting it on an existing instance changes it and publishes `configured` with `privacy` in `changed`. `events` is now optional: omit it to create or return an instance of a kind an installed plugin declares, which leaves the kind's catalog alone. Omitting it for any other kind is still `400 invalid_request`. `kind_owned` now guards only the kind catalog: registering an instance of a plugin's kind never conflicts with it.
+
+### Publishing a plugin-declared kind has new refusals
+
+`custom-objects.publish` on an instance of a kind that an installed plugin declares (or that crossed from another machine):
+
+- `404 not_here` when this machine holds only a stub of the object. Details are `{ id, home_machine }`; ask the home machine.
+- `409 kind_inert` when the kind's plugin is no longer installed and enabled.
+- `403 forbidden` unless the caller is the kind's owning app or holds the instance's publish token.
+
+Instances of kinds an app registered itself publish as before.
+
+### Watching with `link` and `watcher_machine` (additive)
+
+`POST /v1/objects/:ref/watch` and `DELETE …/watch` take an optional `watcher` ref naming a node or a custom object. A non-person app caller can name a node as the `watcher` when the object is one it owns and it holds `crtr:objects:link:<target of the watcher>`: the node then watches the object. Any miss, whatever the cause, is `404 not_found`. `watcher_machine` (body field; query parameter on DELETE) names the machine of an account's other node as the watcher; crtrd keeps a local stand-in for that node, and an event for a node that never watched the stand-in locally still reaches the node. A `watcher_machine` that is not one of the account's machines is `404`; an unreachable directory is `503 runtime_unreachable`. Custom-object watchers behave as before.
+
+A linked node receives the object's events even when it could not read the object by its own access. crtrd keeps the linking app on the watch and checks its scope and ownership again at each publish, so a revoked scope or token stops new deliveries. Across machines, both the object's home machine and the node's machine need this release.
+
+### Reading: `kind_decl`, privacy and plugin read text (additive)
+
+`ObjectDTO` gains an optional `kind_decl` (`{ name, description, events, owner }`). The runtime fills it on the object of an `objects.read` answer and of an `objects.watch` answer when the object is an instance of a custom kind, so another machine can hold a stub of it. It grants nothing. `ObjectListItemDTO` extends `ObjectDTO`, so its type carries the field, but list and search answers do not fill it. `privacy` is the field `ObjectDTO` already had: a read answered by another machine now carries the home object's `kind_decl` and `privacy` into the reader's stub, so a stub is never more readable than its home object.
+
+A read of an instance of a plugin kind whose manifest sets `read.command` runs that leaf on the home machine (15 s deadline for exec and provider plugins alike), outside the canvas transaction, and returns its `markdown` as `text`. The `read` event and the read watch are recorded once. Access is checked again after the leaf returns, and a reader who lost it gets `not_found`; an object deleted while the leaf ran answers `state: "deleted"`, and one that vanished answers `not_found`. If the leaf cannot answer (plugin not installed or disabled, timeout, no string `markdown`), `text` is the last announcement followed by `\ncontent unavailable: <reason>`. Such a read adds `data.content`: `"live"` or `"unavailable"`. A kind that is no longer declared by an installed plugin, a kind without `read.command`, and every other object read as before, with no `data.content`.
+
+### Migrations v89–v91
+
+The canvas database gains `object_kinds.read_json`, `object_kinds.source` (`register`, `manifest` or `peer`) and `object_kinds.declared` (v89), a `peer_ingested_destinations` table recording each event destination already ingested from another machine (v90), and `watches.link_app`, the app that made a watch through `link` (v91). No app action; an older runtime cannot open a database migrated by this release.
+
+## 0.3.483
+
+### `unavailable`, `step` and `setupLink` on `grant.get` dependencies (additive for the SDK; a type change for exhaustive switches)
+
+- `SetupState` gains `unavailable`: the provider does not offer this setup to the person's account. It is not `failed`. If you `switch` over `state` exhaustively, add a case; show `message` and do not link `next`.
+- `ProviderDependency` gains an optional `step: string` (for example `researching`, or `downloaded` on `device`). Its values belong to the provider and may grow: ignore one you do not know. A change to `step` alone changes `grant.get`'s `version`, so `oauth.watchGrants` delivers it.
+- `dependencies` keys may be dotted setup ids such as `context.deep`.
+- New `setupLink(dependency, {returnTo})` returns `dependency.next` with `return_to` set and URL-encoded, keeping the query `next` already has (such as `client_id`). Use it instead of building the link yourself.
+- A runtime older than this release drops a dependency whose state is `unavailable` and silently loses `step`, so an app that reads either needs a runtime on this release.
+
 ## 0.3.482
 
 ### `runs.start` accepts `deadline` (additive, no app change)

package/dist/builtin-memory/northlight-apps/concepts/providers.md

@@ -52,11 +52,11 @@ A call is refused when the scope is missing from the grant. The refusal is an `A
 
 Some apps do not work until a provider is set up for the person. Name it under **What your app requires** on the **What it asks for** tab. The person is then taken through that provider's setup the first time they sign in. Context, for example, asks for a profile URL, and its state stays `pending` for a few minutes afterwards.
 
-Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per required provider, keyed by provider id (or `{}` when the app requires none):
+Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per setup id the app requires or lists as optional, plus any the directory implies (such as `device` for `context.deep`), keyed by setup id (or `{}` when it has none):
 
 ```ts
 const {dependencies} = await runtime.grant.get();
-const context = dependencies['context']; // {state, message?, next} or undefined
+const context = dependencies['context']; // {state, message?, next, step?} or undefined
 if (context?.state !== 'ready') {
   // Show context.message and link context.next; never hard-code either.
 }
@@ -68,8 +68,9 @@ if (context?.state !== 'ready') {
 | `pending` | The provider is working. |
 | `ready` | Calls that depend on it work. |
 | `failed` | Setup failed. `message` says why. |
+| `unavailable` | The provider does not offer this to the person's account. `message` says so; there is nothing for them to do. |
 
-`message` is the provider's own sentence, present for `pending` and `failed`. `next` is the absolute URL of the setup page for this provider and your app; add a `return_to` query parameter with your app's registered origin so the person returns to you. An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [[northlight-apps/guides/grant-changes]].
+`message` is the provider's own sentence, present for `pending`, `failed` and `unavailable`. `step` is present when the provider reports where things stand (for example `researching`); its values may grow, so ignore one you do not know. `next` is the absolute URL of the setup page for this provider and your app; `setupLink(dependency, {returnTo})` from `@north-light/sdk` adds a `return_to` with your app's registered origin so the person returns to you, and keeps the query `next` already carries. A key can contain a dot (`context.deep`). An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [[northlight-apps/guides/grant-changes]].
 
 ## Checked and not checked
 

package/dist/builtin-memory/northlight-apps/guides/grant-changes.md

@@ -41,31 +41,33 @@ await watcher.stop();
 
 ## Wait on a provider your app requires
 
-An app whose registration `requires` a provider (the console's **What your app requires**) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one entry per required provider, keyed by provider id, or `{}` when the app requires none. Read it on each request that needs the provider; do not store it.
+An app whose registration `requires` a provider (the console's **What your app requires**) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one entry per setup id the app requires or lists as optional (plus any the directory implies, such as `device` for `context.deep`), keyed by setup id, or `{}` when it has none. Read it on each request that needs the provider; do not store it.
 
 ```ts
-import type {ProviderDependency} from '@north-light/sdk';
+import {setupLink, type ProviderDependency} from '@north-light/sdk';
 
-// ProviderDependency is { state: 'not_started' | 'pending' | 'ready' | 'failed'; message?: string; next: string }.
+// ProviderDependency is { state: 'not_started' | 'pending' | 'ready' | 'failed' | 'unavailable'; message?: string; next: string; step?: string }.
 const {dependencies} = await runtime.grant.get();
 const context: ProviderDependency | undefined = dependencies['context'];
 if (context?.state !== 'ready') {
   // Show the provider's own sentence and link its setup page; never hard-code either.
-  const setup = context && new URL(context.next);
-  setup?.searchParams.set('return_to', 'https://app.example.com'); // your registered redirect origin
+  // Nothing to link when the provider does not offer this to the person (`unavailable`).
+  const next = context && context.state !== 'unavailable' ? setupLink(context, {returnTo: 'https://app.example.com'}) : undefined; // your registered redirect origin
   throw new AppError('provider_setup_pending', context?.message ?? 'Finish setting up Context, then try again.', {
     status: 403,
     retryable: false,
-    details: {provider: 'context', state: context?.state ?? 'not_started', message: context?.message, next: setup?.href},
+    details: {provider: 'context', state: context?.state ?? 'not_started', message: context?.message, next},
   });
 }
 ```
 
 `AppError` stands for your app's own typed error ([[northlight-apps/errors]]).
 
-- `state` is `not_started` (the person has not done their part), `pending` (the provider is working), `ready` or `failed`.
-- `message` is the provider's own sentence for `pending` and `failed`. It is absent for `not_started` and `ready`, so keep a short fallback.
-- `next` is the absolute URL of the directory's setup page for this provider and your app. Append `return_to` (your app's registered redirect origin) so the person comes back to you.
+- `state` is `not_started` (the person has not done their part), `pending` (the provider is working), `ready`, `failed`, or `unavailable` (the provider does not offer this to the person's account; there is nothing for them to do, so do not link `next`).
+- `message` is the provider's own sentence for `pending`, `failed` and `unavailable`. It is absent for `not_started` and `ready`, so keep a short fallback.
+- `step` is present when the provider reports where the person or the work is, for example `researching`. Its values belong to the provider and may grow: show a known one in your own words and ignore an unknown one. A change to `step` alone changes the grant's `version`, so `watchGrants` delivers it.
+- `next` is the absolute URL of the directory's setup page for this provider and your app. Use `setupLink(dependency, {returnTo})` to add `return_to` (your app's registered redirect origin) so the person comes back to you. It keeps the query `next` already has, such as `client_id`, and encodes `returnTo`; do not build the URL yourself.
+- A key can contain a dot. `context.deep` is a level of the `context` provider; read it as `dependencies['context.deep']`.
 - An entry is missing when the runtime has not synced the grant since the app began requiring the provider. Treat it as `not_started`.
 
 Refuse the dependent operation with `provider_setup_pending` (403), carrying `state`, `message` and `next` in `details`. To act when the state turns `ready`, use `watchGrants` above instead of polling.