@north-light/sdk 0.3.521 → 0.3.523

package/dist/oauth/app-token.d.ts

@@ -10,16 +10,26 @@ export interface AppToken {
     runtimeUrl: string;
     expiresAt: number;
 }
+/** The app's own directory API token: what its `client_credentials` request with no `sub` answers. */
+export interface DirectoryApiToken {
+    accessToken: string;
+    expiresAt: number;
+}
 /** Reads the directory's answer into an `AppToken`; `expiresAt` is the token's own `exp`, else `expires_in` from now. */
 export declare function appTokenFrom(response: AppTokenResponse, now?: number): AppToken;
+/** Reads the directory's answer to a `client_credentials` request with no `sub` into a `DirectoryApiToken`. */
+export declare function directoryApiTokenFrom(response: AppTokenResponse, now?: number): DirectoryApiToken;
 /** A token stays usable until this long before its expiry. */
 export declare const APP_TOKEN_SKEW_MS = 60000;
-/** One minted app token per person, shared by every client of that person and by concurrent callers (one mint in flight per person). */
-export declare class AppTokenCache {
+/** One minted token per key (a person's user id; the directory API token has one key), shared by every caller of that key (one mint in flight per key). */
+export declare class AppTokenCache<T extends {
+    accessToken: string;
+    expiresAt: number;
+} = AppToken> {
     private readonly mint;
     private readonly tokens;
     private readonly minting;
-    constructor(mint: (userId: string) => Promise<AppToken>);
-    /** The cached token while it has more than a minute left, else a fresh mint. `rejected` is the token a runtime just answered 401 to: it is never served again. */
-    get(userId: string, rejected?: string): Promise<AppToken>;
+    constructor(mint: (userId: string) => Promise<T>);
+    /** The cached token while it has more than a minute left, else a fresh mint. `rejected` is the token a server just answered 401 to: it is never served again. */
+    get(userId: string, rejected?: string): Promise<T>;
 }

package/dist/oauth/app-token.js

@@ -5,17 +5,25 @@ export function appTokenFrom(response, now = Date.now()) {
     if (typeof response.access_token !== 'string' || !response.access_token || typeof response.runtimeUrl !== 'string' || !response.runtimeUrl) {
         throw new CrouterError('Directory returned an incomplete app token (access_token and runtimeUrl are required)');
     }
-    const exp = decodeJwt(response.access_token).exp;
-    const expiresAt = typeof exp === 'number' ? exp * 1_000
-        : typeof response.expires_in === 'number' ? now + response.expires_in * 1_000
-            : undefined;
+    return { accessToken: response.access_token, runtimeUrl: response.runtimeUrl, expiresAt: expiryOf(response.access_token, response.expires_in, now) };
+}
+/** Reads the directory's answer to a `client_credentials` request with no `sub` into a `DirectoryApiToken`. */
+export function directoryApiTokenFrom(response, now = Date.now()) {
+    if (typeof response.access_token !== 'string' || !response.access_token) {
+        throw new CrouterError('Directory returned an incomplete directory API token (access_token is required)');
+    }
+    return { accessToken: response.access_token, expiresAt: expiryOf(response.access_token, response.expires_in, now) };
+}
+function expiryOf(accessToken, expiresIn, now) {
+    const exp = decodeJwt(accessToken).exp;
+    const expiresAt = typeof exp === 'number' ? exp * 1_000 : typeof expiresIn === 'number' ? now + expiresIn * 1_000 : undefined;
     if (expiresAt === undefined)
-        throw new CrouterError('Directory returned an app token with no expiry');
-    return { accessToken: response.access_token, runtimeUrl: response.runtimeUrl, expiresAt };
+        throw new CrouterError('Directory returned a token with no expiry');
+    return expiresAt;
 }
 /** A token stays usable until this long before its expiry. */
 export const APP_TOKEN_SKEW_MS = 60_000;
-/** One minted app token per person, shared by every client of that person and by concurrent callers (one mint in flight per person). */
+/** One minted token per key (a person's user id; the directory API token has one key), shared by every caller of that key (one mint in flight per key). */
 export class AppTokenCache {
     mint;
     tokens = new Map();
@@ -23,7 +31,7 @@ export class AppTokenCache {
     constructor(mint) {
         this.mint = mint;
     }
-    /** The cached token while it has more than a minute left, else a fresh mint. `rejected` is the token a runtime just answered 401 to: it is never served again. */
+    /** The cached token while it has more than a minute left, else a fresh mint. `rejected` is the token a server just answered 401 to: it is never served again. */
     get(userId, rejected) {
         const cached = this.tokens.get(userId);
         if (cached && cached.accessToken !== rejected && cached.expiresAt - Date.now() > APP_TOKEN_SKEW_MS)

package/dist/oauth/index.d.ts

@@ -128,6 +128,7 @@ export declare class OAuth2Client {
     private readonly timeoutMs;
     private readonly store;
     private readonly appTokens;
+    private readonly directoryApiTokens;
     private jwks?;
     private discoveryPromise?;
     /** One refresh per (user, refresh token) in this process; a client holding a newer token never joins an older refusal. */
@@ -242,6 +243,18 @@ export declare class OAuth2Client {
      */
     appClient(userId: string): Promise<ConnectedCrouter>;
     private mintAppToken;
+    private mintDirectoryApiToken;
+    /**
+     * The app's own directory API token (`sub=app:<clientId>`, audience `<issuer>/v1`): the bearer for the directory's `/v1` routes
+     * called as the app itself, not for a person. The SDK signs a `client_credentials` request with the `OAuth2Client`'s key
+     * (`private_key_jwt`) and no `sub` (a `sub` would mint a person's runtime token, see `appClient`). The token is cached until a
+     * minute before it expires, and concurrent callers share one mint.
+     *
+     * Pass `rejected`, the token the directory just answered 401 to, to get a different one: the cached copy is dropped and the
+     * SDK mints again, so `const t = await oauth.directoryToken(); … 401 … oauth.directoryToken(t)` re-mints once. Errors are the
+     * token request's: `invalid_client` is a 401 `unauthorized` naming the key, a directory 5xx or a 429 has `retryable` true.
+     */
+    directoryToken(rejected?: string): Promise<string>;
     /**
      * Follow the app's background runs until each comes to rest, and hand each ending to `onEnded` (see
      * `RunWatchOptions`). Runs are opened with `client(userId)`, so refusals reach `onRefusal`. Call `start()`.

package/dist/oauth/index.js

@@ -6,7 +6,7 @@ import { Crouter } from '../client.js';
 import { withinDeadline } from '../resources/request.js';
 import { RunWatcher } from '../resources/run-watcher.js';
 import { GrantWatcher } from '../resources/grant-watcher.js';
-import { AppTokenCache, appTokenFrom } from './app-token.js';
+import { AppTokenCache, appTokenFrom, directoryApiTokenFrom } from './app-token.js';
 import { attachRefusal, isRefusalCode, refusalKindOf } from './refusal.js';
 export { authorizationRefusalOf, refusalOf } from './refusal.js';
 /** A connection store for one process (local development and tests): its lock does not reach other processes. */
@@ -113,6 +113,7 @@ export class OAuth2Client {
     timeoutMs;
     store;
     appTokens = new AppTokenCache((userId) => this.mintAppToken(userId));
+    directoryApiTokens = new AppTokenCache(() => this.mintDirectoryApiToken());
     jwks;
     discoveryPromise;
     /** One refresh per (user, refresh token) in this process; a client holding a newer token never joins an older refusal. */
@@ -453,6 +454,22 @@ export class OAuth2Client {
     async mintAppToken(userId) {
         return appTokenFrom(await this.tokenResponse({ grant_type: 'client_credentials', sub: userId }));
     }
+    async mintDirectoryApiToken() {
+        return directoryApiTokenFrom(await this.tokenResponse({ grant_type: 'client_credentials' }));
+    }
+    /**
+     * The app's own directory API token (`sub=app:<clientId>`, audience `<issuer>/v1`): the bearer for the directory's `/v1` routes
+     * called as the app itself, not for a person. The SDK signs a `client_credentials` request with the `OAuth2Client`'s key
+     * (`private_key_jwt`) and no `sub` (a `sub` would mint a person's runtime token, see `appClient`). The token is cached until a
+     * minute before it expires, and concurrent callers share one mint.
+     *
+     * Pass `rejected`, the token the directory just answered 401 to, to get a different one: the cached copy is dropped and the
+     * SDK mints again, so `const t = await oauth.directoryToken(); … 401 … oauth.directoryToken(t)` re-mints once. Errors are the
+     * token request's: `invalid_client` is a 401 `unauthorized` naming the key, a directory 5xx or a 429 has `retryable` true.
+     */
+    directoryToken(rejected) {
+        return this.directoryApiTokens.get('directory', rejected).then((token) => token.accessToken);
+    }
     /**
      * Follow the app's background runs until each comes to rest, and hand each ending to `onEnded` (see
      * `RunWatchOptions`). Runs are opened with `client(userId)`, so refusals reach `onRefusal`. Call `start()`.

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.521"
+  sdk-version: "0.3.523"
 ---
 
 # Building a Northlight app
@@ -11,7 +11,7 @@ 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.521`. 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.523`. 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
 

package/dist/testing/cloud.d.ts

@@ -279,7 +279,7 @@ export declare class FakeCloud {
     private route;
     private runIntercepts;
     private directory;
-    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    /** `grant_type=client_credentials`: with `sub`, the directory's per-user runtime-token mint; without, the app's own directory API token. The client assertion is not verified. */
     private mint;
     private refresh;
     /** `grant_type=authorization_code`: the code `authorize` issued, once. The client assertion and PKCE verifier are not verified. */

package/dist/testing/cloud.js

@@ -520,12 +520,14 @@ export class FakeCloud {
             return this.exchange(params, call);
         return credentials ? this.mint(params, call) : this.refresh(params, presented, call);
     }
-    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    /** `grant_type=client_credentials`: with `sub`, the directory's per-user runtime-token mint; without, the app's own directory API token. The client assertion is not verified. */
     mint(params, call) {
         const sub = params.get('sub');
         if (!sub) {
-            call.answer = 400;
-            return Response.json({ error: 'unauthorized_client' }, { status: 400 });
+            const now = Math.floor(this.clock.now() / 1000);
+            const clientId = params.get('client_id') ?? '';
+            const access_token = unsignedJwt({ sub: `app:${clientId}`, client_id: clientId, aud: `${this.issuer}/v1`, exp: now + 600, iat: now, serial: ++this.tokenSerial });
+            return Response.json({ access_token, token_type: 'Bearer', expires_in: 600 });
         }
         const user = this.users.get(sub);
         const refused = (description, answer) => { call.answer = answer; return Response.json({ error: 'invalid_grant', error_description: description }, { status: 400 }); };

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.521";
+export declare const SDK_VERSION = "0.3.523";
 /** 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.521';
+export const SDK_VERSION = '0.3.523';
 // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.521",
+  "version": "0.3.523",
   "crouterContract": "1.25",
   "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.521",
-    "@north-light/identity": "0.3.521",
+    "@north-light/api": "0.3.523",
+    "@north-light/identity": "0.3.523",
     "jose": "^6.2.1"
   },
   "peerDependencies": {