@vendure-platform/console-auth 1.0.0-major.202609091053.0.0

package/README.md

@@ -0,0 +1,335 @@
+# @vendure-platform/console-auth
+
+Browser login against Vendure Console, the user-level credential store that
+keeps the result, and the onboarding flow both tools run on top of it. Shared by
+`@vendure-platform/create` and `@vendure-platform/cli` so there is one login and
+one way to link a project, rather than one per tool.
+
+This package is public and MIT because `@vendure-platform/create` runs under
+`npx` for people who hold no registry token. It has no runtime dependencies
+beyond `tslib`.
+
+## What it does
+
+```ts
+import { loginAndStoreConsoleToken, resolveStoredConsoleToken } from '@vendure-platform/console-auth';
+
+const token = (await resolveStoredConsoleToken()) ?? (await loginAndStoreConsoleToken({ client: 'create' }));
+```
+
+`resolveStoredConsoleToken` returns a usable access token from the stored
+credential, refreshing it first when it has expired and carries a refresh token.
+It returns `undefined` when there is nothing usable, which is the caller's cue to
+offer a login. The refresh runs under the cross-process lock described in
+"Sharing the credential across processes", so two commands running at once
+cannot spend the same single-use refresh token.
+
+## Onboarding a project
+
+`create` has to sign a person in, find or make a Console Project, give it an
+edition, and write the Project Link Manifest. It runs under `npx` and cannot
+depend on `@vendure/cli`, so that flow lives here.
+
+`vendure console link` does none of it. `@vendure/cli` owns the link: the
+endpoints, the approval, the browser, the polling and the manifest.
+`@vendure-platform/cli` contributes only what comes after one, through the
+CLI's `afterConsoleLink` hook. The manifest reader and writer here stay in step
+with the CLI's own through `project-link-conformance.spec.ts` in that package,
+which runs both over the same inputs.
+
+```ts
+import { ConsoleApi, establishProjectLink } from '@vendure-platform/console-auth';
+
+const api = new ConsoleApi({ apiOrigin, getAccessToken: () => token });
+const link = await establishProjectLink({ projectRoot, api, interaction, reuseExistingLink: true });
+```
+
+`establishProjectLink` is the whole flow. `selectConsoleProject` and
+`writeProjectLink` are its two halves, because `create` needs the edition while
+its prompts are still running and cannot write a manifest until the directory
+exists.
+
+Every question is a call on `ConsoleOnboardingInteraction` rather than a prompt.
+`create` draws with `@clack/prompts`, and no prompt library belongs in this
+package. Any of
+those calls may throw `ConsoleOnboardingCancelled`, which means the person
+stopped and nothing should be written.
+
+This package writes no credential of either kind:
+
+-   The account-level session is written by the login that produced the token
+    the flow runs on, which is this package's own store below.
+-   The project-scoped Environment Credential is written only by
+    `@vendure-platform/cli`. Nothing here can reach it, which is what keeps the
+    two stores apart in the module graph as well as on disk.
+
+`acquireRegistryAccess` gets the Registry Access Token for a Project. Console
+returns the value once, so a lost response leaves a token that exists in Console
+and nowhere else. Creating a second one under the same name is refused.
+The caller recovers from that refusal by finding the token of that name in the
+list and rotating it, only after confirming, because rotating stops the old one
+working.
+
+## Where the credential lives
+
+`~/.vendure/console-credentials.json`, directory mode `0700`, file mode `0600`,
+written through a temporary file and a rename so a reader never sees a
+half-written token.
+
+The repository has no `XDG_CONFIG_HOME` precedent, so this does not invent one.
+
+This is an **account-level** credential and it is deliberately not the same thing
+as the per-project development credential `@vendure-platform/cli` keeps in
+`<projectRoot>/.vendure/credentials.json`. That one authenticates one
+environment of one project. This one is worth as much as the person's Console
+password across every project they own, so it never goes near a project
+directory that someone is about to `git init`.
+
+A missing file, an unreadable one, malformed JSON, or a credential issued by a
+different Console app or API origin all read as "no credential". A corrupt cache is not worth
+stopping a scaffold over.
+
+Schema version 2 records the issuing API origin. Reads, refreshes, and login
+validate and normalize both origins. A token is reused only when both origins
+match. Schema version 1 has no known API issuer and requires a new login.
+Logging in against another API replaces the single cache entry, but that entry
+cannot be reused against production.
+
+Only one thing removes a stored credential: a refresh that Console refused,
+observed under the lock described below, against a refresh token that is still
+the stored one. There is still no `vendure console logout` command, because
+nothing calls for one today.
+
+## Sharing the credential across processes
+
+Console rotates the refresh token on use and refuses the spent one. The second
+process to present the same token is left with nothing, and if it then writes
+its own stale pair back it overwrites a live session with a dead one. Two
+processes are ordinary: `vendure dev` runs for hours while other commands run in
+another terminal, and Vendure Cloud commands read the same file.
+
+So every step that spends a refresh token or rewrites the credential goes
+through one lock, because the double spend stays reachable through any step
+left out. `resolveStoredConsoleToken`, `refreshStoredConsoleToken` and
+`loginAndStoreConsoleToken` take it for you and are the whole of what this
+package writes credentials from. `writeConsoleCredential` is exported so a test can
+put a credential in place, and it takes no lock: any other caller has to wrap it
+in `withConsoleSessionLock`.
+
+Vendure Cloud implements this from its own repository and its own release train.
+The protocol is written down here rather than shared as code, because the two
+sides have only the filesystem in common. TypeScript callers import
+`withConsoleSessionLock`.
+
+### The lock file
+
+`~/.vendure/console-credentials.lock`, beside the credential it guards.
+
+Take the lock by creating that file with `O_CREAT | O_EXCL` at mode `0600`
+(`wx` in Node). The create either wins or fails with `EEXIST`, with no window in
+between, and that is the whole mechanism. Write one line of JSON into it:
+
+```json
+{ "token": "3f0c1a6e-9c2b-4d51-9f0a-2e7c5b1d8a44", "pid": 4242, "acquiredAt": "2026-01-01T12:00:00.000Z" }
+```
+
+`token` is new for every acquisition and is what makes releasing safe. `pid` and
+`acquiredAt` are for a person looking at a lock that will not go away.
+
+Release the lock by reading the file and removing it only while `token` still
+matches the one you wrote. A lock carrying another token was broken as stale and
+taken over while you were working, and removing it would let a third process in
+while the second one writes.
+
+The lock is not reentrant. `resolveStoredConsoleToken`, `refreshStoredConsoleToken`
+and `loginAndStoreConsoleToken` take it themselves, so wrapping one of them in
+`withConsoleSessionLock` waits out the whole wait budget and then fails: the
+outer lock is held by a process that is alive and beating, which is the one
+thing a waiter never breaks.
+
+### The budgets
+
+| Budget    | Value | Meaning                                                            |
+| --------- | ----- | ------------------------------------------------------------------ |
+| Stale     | 30s   | A lock whose mtime is older than this may be taken over by anyone. |
+| Wait      | 30s   | How long to wait for a lock somebody else holds before giving up.  |
+| Heartbeat | 10s   | How often a holder touches its own lock while it works.            |
+
+Never make the wait budget shorter than the stale budget. A waiter that gave up
+sooner could give up while the holder was dead but not yet stale, and then "I
+gave up waiting" would stop meaning "the holder is gone".
+
+Equal budgets only make them the same condition if both are measured against
+the same clock. A lock mtime carries a fraction of a millisecond that
+`Date.now()` does not, so compare whole milliseconds. Look at the lock once more
+when the budget runs out, too: it can cross the stale boundary while the check
+before it is still reading.
+
+Touch your own lock while you hold it, a third of the stale budget apart. That
+is what makes the stale budget measure a holder that has stopped rather than one
+that is slow: without it, a hold that runs long on a loaded machine is broken
+while it is still working, and two processes refresh at once. Two missed beats
+are allowed before anyone may act on the silence. A participant that does not
+beat is not broken by this, it is only judged on how long its work takes, which
+is what every participant was judged on before.
+
+Bound that work anyway. The longest legitimate hold is the two token requests a
+refresh makes when the first is refused and a rotated pair is on disk to try
+instead, and each request has to carry a deadline that covers reading the answer
+as well as getting it, or a server that sends headers and then stops sending
+holds the lock for as long as it likes. This package gives each request 10
+seconds, so the work inside a lock is 20 seconds at the outside.
+
+Take a stale lock over by renaming it aside to a name of your own, not by
+removing it in place. `rename` is one operation, so one waiter moves the file
+and the rest find it gone and go back to creating. Removing it by path lets a
+second waiter, still holding its reading of a file the first waiter has already
+removed, delete the fresh lock the first waiter created in its place, and then
+two processes hold the lock at once. Read what you moved: if it is not the lock
+you judged stale, somebody took the lock in between, so `link` it back where it
+was and leave it alone.
+
+A window remains between reading the lock and moving it, so treat this as
+narrowed rather than closed. A lock taken inside that window is moved aside by
+somebody who judged the lock before it, and putting it back fails if a third
+lock has landed by then, which leaves two holders. The recovery below is what
+makes that survivable: two holders spend one grant between them and the loser
+reuses what the winner wrote, so the cost is a wasted request rather than a
+lost session.
+
+While you hold the lock, read the credential again. Waiting for the lock is the
+usual way to find out that another process has refreshed: by the time you get
+in, the pair you read beforehand is the stale copy and the one on disk is live.
+A credential that is usable when read under the lock is the answer, and no grant
+needs spending.
+
+### When Console refuses the refresh
+
+Re-read the credential before believing the refusal. A single-use refresh token
+is usually refused because another process spent it first, and the pair that
+process got back is already on disk. Use that pair.
+
+If the stored refresh token is still the one that was just refused, and the lock
+was held across both the refusal and the read, then nothing can have rotated it
+and the session really is over. Only there may the credential be removed. Never
+remove or overwrite it on the strength of a refusal observed without the lock.
+
+Tell a refusal apart from a failure, and read the body to do it. Console names a
+refused grant with `"code": "cli_session.invalid_grant"`. A 4xx that does not
+name one is somebody other than Console answering: an API origin pointed at the
+wrong host returning 404, a proxy in front of Console returning 403, a gateway
+that wants a credential of its own returning 401. A timeout, an unreachable
+host, a 5xx and a malformed response say nothing about the refresh token
+either. All of them leave the credential untouched, and the next attempt gets a
+straight answer.
+
+When you cannot take the lock, do nothing: no refresh, no write, no removal.
+Because the wait budget covers the stale budget, failing to acquire means the
+filesystem refused you or other processes kept taking the lock first. Neither
+says anything about the session, so report it as a temporary failure and leave
+the credential where it is. Reporting it as "no credential" is not that, because
+the caller answers that by sending a person to the browser to log in over a
+session that is fine.
+
+## Trusted origins
+
+Production pairs `https://console.vendure.io` with `https://api.vendure.io`.
+Staging pairs `https://staging.console.vendure.io` with `https://staging.api.vendure.io`.
+Supplying only the staging API selects the staging app for browser login and
+cache lookup. Supplying only the staging app selects its API. Explicit mixed
+production and staging pairs are rejected. Loopback hosts remain allowed for
+local development and tests.
+
+Any URL carrying a path, a query, a fragment, or credentials is rejected before
+use, and every request sets `redirect: 'error'`. A host allow-list on its own is
+not enough: those are the shapes that let a URL send the browser somewhere else
+while the hostname still reads correctly.
+
+## Console frontend contract
+
+> Console serves all of this as of Console #121. The route is
+> `apps/console/src/routes/cli-auth.tsx` and the token endpoint is
+> `apps/api/src/cli-sessions/cli-auth.controller.ts`. What is written down here
+> is what both sides implement, so a change on either side changes this file.
+
+The user logs in on the Console web app, not on the API and not on an identity
+provider this CLI picked. That way the address bar shows a host they already
+trust.
+
+### `GET https://console.vendure.io/cli-auth`
+
+| Query param             | Required | Meaning                                                        |
+| ----------------------- | -------- | -------------------------------------------------------------- |
+| `client`                | yes      | `create` or `cli`. Console names the tool on the confirm page. |
+| `redirect_uri`          | yes      | `http://127.0.0.1:<port>/auth/callback`. Loopback only.        |
+| `state`                 | yes      | Opaque, 32 random bytes base64url. Returned verbatim.          |
+| `code_challenge`        | yes      | PKCE challenge, base64url SHA-256 of the verifier.             |
+| `code_challenge_method` | yes      | Always `S256`.                                                 |
+
+Console behaviour:
+
+1. If the visitor is not signed in, show the normal Console login first.
+2. Show a confirmation page naming the tool from `client` and the account that
+   will be authorized.
+3. On approval, mint a short-lived single-use authorization code bound to the
+   account and to `code_challenge`, then `302` to
+   `redirect_uri?code=<code>&state=<state>`.
+4. On refusal, `302` to `redirect_uri?error=access_denied&state=<state>`.
+
+Console must reject any `redirect_uri` that is not loopback. That check is what
+stops an attacker sending a code somewhere else.
+
+### `POST https://api.vendure.io/v1/auth/cli/token`
+
+Body for the initial exchange:
+
+```json
+{
+    "grant_type": "authorization_code",
+    "code": "...",
+    "code_verifier": "...",
+    "redirect_uri": "http://127.0.0.1:54321/auth/callback"
+}
+```
+
+Body for a refresh:
+
+```json
+{ "grant_type": "refresh_token", "refresh_token": "..." }
+```
+
+Response:
+
+```json
+{
+    "access_token": "...",
+    "token_type": "Bearer",
+    "expires_in": 3600,
+    "refresh_token": "..."
+}
+```
+
+`refresh_token` is optional. `expires_in` is required: a session assumed to last
+longer than it does fails later, at the project lookup, where the cause is no
+longer visible.
+
+A refresh token that has already been spent, expired or been revoked is refused
+with `400` and the Console error convention, which names the condition under
+`code` rather than under the OAuth `error`:
+
+```json
+{ "code": "cli_session.invalid_grant", "message": "This refresh token was already used." }
+```
+
+That `code` is the one thing that ends a session. It is the only code the token
+endpoint refuses with, so it covers a token request Console could not read at
+all as well as a grant it will not honour again. On the refresh path that
+distinction does not arise: the request carries `grant_type` and
+`refresh_token`, both well formed, so the only thing left for Console to refuse
+is the grant. Any other status or body reads as a request that failed rather
+than a grant that was judged, and leaves the stored credential alone. `message`
+is for a person; nothing branches on it.
+
+The `access_token` is sent as `Authorization: Bearer <token>` to
+`GET /v1/projects/editions`, which Console serves from
+`apps/api/src/projects/projects.controller.ts`.

package/dist/browser-auth.d.ts

@@ -0,0 +1,48 @@
+/** Identifies the calling tool so Console can name it on the confirmation page. */
+export type ConsoleAuthClient = 'create' | 'cli';
+export interface ConsoleSession {
+    accessToken: string;
+    /** Absolute expiry, ISO-8601. Derived from the `expires_in` Console returns. */
+    expiresAt: string;
+    refreshToken?: string;
+}
+/**
+ * A token grant that did not produce a session.
+ *
+ * `refused` separates "Console judged this grant and said no" from "ask again
+ * later", and only a refusal may end a session. A 503, a timeout, an
+ * unreachable host and a malformed answer all say nothing about whether the
+ * refresh token is still good, so acting on one would log a person out because
+ * their network dropped.
+ */
+export declare class ConsoleTokenGrantError extends Error {
+    readonly refused: boolean;
+    constructor(message: string, refused: boolean);
+}
+export interface BrowserLoginOptions {
+    client: ConsoleAuthClient;
+    appOrigin?: string;
+    apiOrigin?: string;
+    fetch?: typeof globalThis.fetch;
+    openBrowser?: (url: string) => Promise<boolean>;
+    reportAuthorizationUrl?: (url: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    now?: () => Date;
+}
+/**
+ * Log in through the Vendure Console web app and return an account-level
+ * session.
+ *
+ * The browser only ever visits Console. A loopback server on 127.0.0.1 receives
+ * the authorization code, and the code is traded for a token by this process
+ * over HTTPS, so the token never travels through the URL bar or the shell
+ * history.
+ */
+export declare function loginWithBrowser(options: BrowserLoginOptions): Promise<ConsoleSession>;
+/** Trade a refresh token for a fresh session. Same contract as the code exchange. */
+export declare function refreshSession(refreshToken: string, options?: {
+    apiOrigin?: string;
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+}): Promise<ConsoleSession>;

package/dist/browser-auth.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.ConsoleTokenGrantError=void 0,exports.loginWithBrowser=d,exports.refreshSession=h;const e=require("node:child_process"),r=require("node:crypto"),t=require("node:http"),n=require("./origins"),o="127.0.0.1",i="/auth/callback",a="/cli-auth",s="/v1/auth/cli/token",c=3e5,l=1e4,u=31536e3;class ConsoleTokenGrantError extends Error{constructor(e,r){super(e),this.name="ConsoleTokenGrantError",this.refused=r}}async function d(e){var r,a,s,l,u;const{appOrigin:d,apiOrigin:h}=(0,n.consoleOrigins)(e),w=null!==(r=e.fetch)&&void 0!==r?r:globalThis.fetch,g=(0,t.createServer)();try{const r=await T(g),t=`http://${o}:${r}${i}`,n=k(),m=k(),v=p({appOrigin:d,client:e.client,redirectUri:t,state:n,codeVerifier:m}),y=_(g,n,{signal:e.signal,timeoutMs:null!==(a=e.timeoutMs)&&void 0!==a?a:c});y.catch(()=>{}),await(null!==(s=e.openBrowser)&&void 0!==s?s:E)(v).catch(()=>!1)||null===(l=e.reportAuthorizationUrl)||void 0===l||l.call(e,v);const b=await y;return await f({apiOrigin:h,fetch:w,code:b,codeVerifier:m,redirectUri:t,signal:e.signal,now:null!==(u=e.now)&&void 0!==u?u:()=>new Date})}finally{await b(g)}}async function h(e,r={}){var t,o;const i=(0,n.consoleApiOrigin)(r.apiOrigin);return v(await w(i,null!==(t=r.fetch)&&void 0!==t?t:globalThis.fetch,{grant_type:"refresh_token",refresh_token:e},void 0),null!==(o=r.now)&&void 0!==o?o:()=>new Date,e)}function p(e){const r=new URL(a,e.appOrigin);return r.searchParams.set("client",e.client),r.searchParams.set("redirect_uri",e.redirectUri),r.searchParams.set("state",e.state),r.searchParams.set("code_challenge",y(e.codeVerifier)),r.searchParams.set("code_challenge_method","S256"),r.toString()}async function f(e){return v(await w(e.apiOrigin,e.fetch,{grant_type:"authorization_code",code:e.code,code_verifier:e.codeVerifier,redirect_uri:e.redirectUri},e.signal),e.now)}async function w(e,r,t,n){const o=new AbortController,i=()=>o.abort();null==n||n.addEventListener("abort",i,{once:!0});const a=setTimeout(i,l);try{let n;try{n=await r(`${e}${s}`,{method:"POST",redirect:"error",signal:o.signal,headers:{Accept:"application/json","Content-Type":"application/json"},body:JSON.stringify(t)})}catch{throw new ConsoleTokenGrantError("Could not reach Vendure Console for a token.",!1)}if(!n.ok)throw new ConsoleTokenGrantError(`Vendure Console rejected the token request with HTTP ${n.status}.`,await m(n));try{return await n.json()}catch{throw new ConsoleTokenGrantError("Vendure Console returned malformed JSON for a token.",!1)}}finally{clearTimeout(a),null==n||n.removeEventListener("abort",i)}}exports.ConsoleTokenGrantError=ConsoleTokenGrantError;const g="cli_session.invalid_grant";async function m(e){if(e.status<400||500<=e.status)return!1;try{const{code:r}=JSON.parse(await e.text());return r===g}catch{return!1}}function v(e,r,t){const n=e;if("string"!=typeof(null==n?void 0:n.access_token)||!n.access_token)throw new Error("Vendure Console returned no access token.");if("Bearer"!==n.token_type)throw new Error(`Vendure Console returned an unsupported token type "${String(n.token_type)}".`);if("number"!=typeof n.expires_in||!Number.isInteger(n.expires_in)||n.expires_in<=0||n.expires_in>u)throw new Error("Vendure Console returned no usable token expiry.");const o="string"==typeof n.refresh_token&&n.refresh_token?n.refresh_token:t;return{accessToken:n.access_token,expiresAt:new Date(r().getTime()+1e3*n.expires_in).toISOString(),...o?{refreshToken:o}:{}}}function k(){return(0,r.randomBytes)(32).toString("base64url")}function y(e){return(0,r.createHash)("sha256").update(e).digest("base64url")}function _(e,r,t){return new Promise((n,a)=>{var s,c;let l=!1;const u=e=>{var r;l||(l=!0,clearTimeout(h),null===(r=t.signal)||void 0===r||r.removeEventListener("abort",d),"error"in e?a(e.error):n(e.code))},d=()=>u({error:new Error("Login was interrupted.")}),h=setTimeout(()=>u({error:new Error("Login timed out.")}),t.timeoutMs);null===(s=t.signal)||void 0===s||s.addEventListener("abort",d,{once:!0}),(null===(c=t.signal)||void 0===c?void 0:c.aborted)&&d(),e.on("request",(e,t)=>{var n;const a=new URL(null!==(n=e.url)&&void 0!==n?n:"/",`http://${o}`);if("GET"!==e.method||a.pathname!==i)return void t.writeHead(404).end("Not found");if(a.searchParams.get("state")!==r)return t.writeHead(400).end("Login state did not match. Return to the terminal."),void u({error:new Error("Login state did not match.")});const s=a.searchParams.get("code");if(!s||a.searchParams.has("error"))return t.writeHead(400).end("Login was not completed. Return to the terminal."),void u({error:new Error("Vendure Console did not authorize the login.")});t.writeHead(200,{"Content-Type":"text/plain; charset=utf-8"}),t.end("Login complete. You can close this window."),u({code:s})})})}function T(e){return new Promise((r,t)=>{e.once("error",t),e.listen(0,o,()=>{e.off("error",t);const n=e.address();n&&"string"!=typeof n?r(n.port):t(new Error("Could not start the local login callback."))})})}function b(e){return e.listening?new Promise(r=>e.close(()=>r())):Promise.resolve()}function E(r){const t="darwin"===process.platform?{executable:"open",args:[r]}:"win32"===process.platform?{executable:"rundll32",args:["url.dll,FileProtocolHandler",r]}:{executable:"xdg-open",args:[r]};return new Promise(r=>{const n=(0,e.spawn)(t.executable,t.args,{detached:!0,stdio:"ignore"});n.once("error",()=>r(!1)),n.once("spawn",()=>{n.unref(),r(!0)})})}

package/dist/console-api.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Console answered, and the answer was a refusal. `code` carries the Console
+ * error convention (`project.not_found`, `auth.permission_denied`, and so on),
+ * which is what callers branch on: the status alone cannot tell a missing
+ * permission from a missing Project.
+ */
+export declare class ConsoleApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    /**
+     * The parsed error body. Console puts the actionable part of a refusal
+     * beside `code`: an Evaluation denial carries `reason` and
+     * `nextEligibleAt`, and neither survives being flattened into a string.
+     */
+    readonly body?: Record<string, unknown>;
+    constructor(status: number, code: string | undefined, message: string, 
+    /**
+     * The parsed error body. Console puts the actionable part of a refusal
+     * beside `code`: an Evaluation denial carries `reason` and
+     * `nextEligibleAt`, and neither survives being flattened into a string.
+     */
+    body?: Record<string, unknown>);
+}
+/** The request never produced an answer. Says nothing about the request itself. */
+export declare class ConsoleApiTransportError extends Error {
+    constructor(message: string);
+}
+export interface ConsoleApiOptions {
+    /** Validated through the shared origin allow-list before anything is sent. */
+    apiOrigin?: string;
+    getAccessToken: () => string | Promise<string>;
+    /** Called once per client when Console reports the access token expired. */
+    refreshAccessToken?: () => void | Promise<void>;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface ConsoleApiRequestOptions {
+    method?: 'GET' | 'POST';
+    body?: unknown;
+    /** Extra request headers. `Idempotency-Key` is the only one in use. */
+    headers?: Record<string, string>;
+}
+/**
+ * The authenticated Console API calls the onboarding flow makes.
+ *
+ * `@vendure-platform/license-guard` carries a client of its own for the
+ * entitlement runtime. This one is not that one and does not import it: that
+ * package declares a peer dependency on `@vendure/core`, and
+ * `@vendure-platform/create` runs under `npx` in a directory that has no
+ * Vendure installed. It also has to send `Idempotency-Key`, which the runtime
+ * client has no reason to.
+ */
+export declare class ConsoleApi {
+    private readonly options;
+    readonly apiOrigin: string;
+    private readonly fetch;
+    private refreshed;
+    constructor(options: ConsoleApiOptions);
+    request<T>(path: string, options?: ConsoleApiRequestOptions): Promise<T>;
+    private send;
+}
+/** Whether Console refused because the session lacks the Permission. */
+export declare function isPermissionDenied(error: unknown): boolean;
+/** Whether Console refused with HTTP 409 and this error code. */
+export declare function isConsoleConflict(error: unknown, code: string): boolean;

package/dist/console-api.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.ConsoleApi=exports.ConsoleApiTransportError=exports.ConsoleApiError=void 0,exports.isPermissionDenied=s,exports.isConsoleConflict=t;const o=require("./origins");class ConsoleApiError extends Error{constructor(o,r,e,s){super(e),this.status=o,this.code=r,this.body=s,this.name="ConsoleApiError"}}exports.ConsoleApiError=ConsoleApiError;class ConsoleApiTransportError extends Error{constructor(o){super(o),this.name="ConsoleApiTransportError"}}exports.ConsoleApiTransportError=ConsoleApiTransportError;const r=1e4,e=65536;class ConsoleApi{constructor(r){var e;this.options=r,this.refreshed=!1,this.apiOrigin=(0,o.consoleApiOrigin)(r.apiOrigin),this.fetch=null!==(e=r.fetch)&&void 0!==e?e:globalThis.fetch}async request(o,r={}){try{return await this.send(o,r)}catch(e){if(e instanceof ConsoleApiError&&401===e.status&&"auth.token_expired"===e.code&&!this.refreshed&&this.options.refreshAccessToken)return this.refreshed=!0,await this.options.refreshAccessToken(),this.send(o,r);throw e}}async send(o,e){var s,t,a,l,p;if(!o.startsWith("/")||o.startsWith("//"))throw new Error("The Vendure Console API path must start with one slash.");const c=await this.options.getAccessToken();if(!c)throw new Error("No Vendure Console session is available.");const d=new AbortController,h=()=>d.abort();null===(s=this.options.signal)||void 0===s||s.addEventListener("abort",h,{once:!0});const u=setTimeout(h,null!==(t=this.options.timeoutMs)&&void 0!==t?t:r);try{const r=await this.fetch(`${this.apiOrigin}${o}`,{method:null!==(a=e.method)&&void 0!==a?a:void 0===e.body?"GET":"POST",redirect:"error",signal:d.signal,headers:{Authorization:`Bearer ${c}`,Accept:"application/json",...void 0===e.body?{}:{"Content-Type":"application/json"},...e.headers},...void 0===e.body?{}:{body:JSON.stringify(e.body)}}),s=await n(r);if(!r.ok){const{code:o,message:e,fields:t}=i(s);throw new ConsoleApiError(r.status,o,null!=e?e:`Vendure Console returned HTTP ${r.status}.`,t)}return s}catch(o){if(o instanceof ConsoleApiError)throw o;if(null===(l=this.options.signal)||void 0===l?void 0:l.aborted)throw new ConsoleApiTransportError("The request was cancelled.");if(o instanceof Error&&"AbortError"===o.name)throw new ConsoleApiTransportError("The Vendure Console request timed out.");throw new ConsoleApiTransportError("Could not reach Vendure Console.")}finally{clearTimeout(u),null===(p=this.options.signal)||void 0===p||p.removeEventListener("abort",h)}}}function s(o){return o instanceof ConsoleApiError&&403===o.status&&"auth.permission_denied"===o.code}function t(o,r){return o instanceof ConsoleApiError&&409===o.status&&o.code===r}async function n(o){const r=await o.text();if(Buffer.byteLength(r,"utf8")>e)throw new ConsoleApiError(o.status,void 0,"The Vendure Console response was too large.");if(r)try{return JSON.parse(r)}catch{throw new ConsoleApiError(o.status,void 0,"Vendure Console returned malformed JSON.")}}function i(o){if(!o||"object"!=typeof o||Array.isArray(o))return{};const r=o;return{code:"string"==typeof r.code?r.code:void 0,message:"string"==typeof r.message?r.message:void 0,fields:r}}exports.ConsoleApi=ConsoleApi;

package/dist/console-projects.d.ts

@@ -0,0 +1,101 @@
+import { ConsoleApi } from './console-api';
+import { type ProjectLinkManifest } from './project-link-manifest';
+/** Product Offer behind a Project's current access. */
+export type ProjectEdition = 'starter' | 'growth' | 'scale' | 'enterprise';
+/** Where that access came from. `none` means the Project has no access at all. */
+export type ProjectEditionSource = 'override' | 'subscription' | 'evaluation' | 'none';
+/** The Offers an Evaluation may be started on. Enterprise is sold, never evaluated. */
+export type EvaluationOfferCode = 'starter' | 'growth' | 'scale';
+export declare const PROJECT_EDITIONS: readonly ProjectEdition[];
+export declare const EVALUATION_OFFER_CODES: readonly EvaluationOfferCode[];
+/**
+ * One ACTIVE Project of the signed-in account with the edition it currently
+ * holds. `edition` is null when no Offer supplies the access, which a support
+ * override granting a bare Capability list produces, so a null edition is a
+ * Project that exists rather than one that is broken.
+ */
+export interface ConsoleProjectEdition {
+    id: string;
+    name: string;
+    edition: ProjectEdition | null;
+    source: ProjectEditionSource;
+}
+export interface ConsoleProject {
+    id: string;
+    name: string;
+    state: 'active' | 'archived';
+}
+export interface ProjectEvaluationState {
+    startState: 'available' | 'already_active' | 'project_inactive' | 'account_evaluation_active' | 'rolling_window';
+    nextEligibleAt: string | null;
+    offerCodes: EvaluationOfferCode[];
+}
+export interface StartedEvaluation {
+    outcome: 'started' | 'existing';
+    offerCode: string;
+    expiresAt: string;
+}
+export interface RegistryAccessConfiguration {
+    registryUrl: string;
+    scope: string;
+}
+export interface RegistryAccessToken {
+    id: string;
+    name: string;
+    state: 'active' | 'expired' | 'revoked';
+}
+export interface IssuedRegistryAccessToken extends RegistryAccessToken {
+    /** Returned once, by the create and rotate routes only. */
+    token: string;
+}
+/** Every ACTIVE Project of the account, with its edition. */
+export declare function listProjectEditions(api: ConsoleApi): Promise<ConsoleProjectEdition[]>;
+/**
+ * Create a Project.
+ *
+ * `idempotencyKey` makes a repeat safe after a lost response: the same key and
+ * the same name return the Project the first request created rather than a
+ * second one. Console answers a repeat that carries a different name with
+ * `project.idempotency_conflict`, which is a caller bug rather than a race, so
+ * it surfaces as-is.
+ */
+export declare function createProject(api: ConsoleApi, input: {
+    name: string;
+    idempotencyKey?: string;
+}): Promise<ConsoleProject>;
+export declare function getProjectEvaluation(api: ConsoleApi, projectId: string): Promise<ProjectEvaluationState>;
+/**
+ * Start an Evaluation.
+ *
+ * Retry-safe: `outcome` reports `existing` when the Project already had the
+ * Evaluation this call would have created, so a repeat after a lost response
+ * does not need to be distinguished from the first attempt.
+ */
+export declare function startProjectEvaluation(api: ConsoleApi, projectId: string, offerCode: EvaluationOfferCode): Promise<StartedEvaluation>;
+/**
+ * Why Console refused to start an Evaluation, or `undefined` when the failure
+ * was something else. `nextEligibleAt` is the only part a person can act on:
+ * it names the date the rolling window reopens.
+ */
+export declare function evaluationDenial(error: unknown): {
+    message: string;
+    reason?: string;
+    nextEligibleAt?: string;
+} | undefined;
+/**
+ * Create an approved Project Link for a Project the signed-in session already
+ * owns, and return its Manifest.
+ *
+ * This is the one-call route, not the browser approval flow: the caller holds
+ * the person's own Console session, so there is nobody left to ask.
+ */
+export declare function linkProject(api: ConsoleApi, projectId: string): Promise<ProjectLinkManifest>;
+export declare function getRegistryAccess(api: ConsoleApi, projectId: string): Promise<RegistryAccessConfiguration>;
+export declare function listRegistryAccessTokens(api: ConsoleApi, projectId: string): Promise<RegistryAccessToken[]>;
+export declare function createRegistryAccessToken(api: ConsoleApi, projectId: string, name: string): Promise<IssuedRegistryAccessToken>;
+export declare function rotateRegistryAccessToken(api: ConsoleApi, projectId: string, tokenId: string): Promise<IssuedRegistryAccessToken>;
+/** The Customer Account the session is scoped to, or `undefined` when it is scoped to none. */
+export declare function readViewerAccount(api: ConsoleApi): Promise<{
+    id: string;
+    name: string;
+} | undefined>;

package/dist/console-projects.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.EVALUATION_OFFER_CODES=exports.PROJECT_EDITIONS=void 0,exports.listProjectEditions=r,exports.createProject=o,exports.getProjectEvaluation=n,exports.startProjectEvaluation=s,exports.evaluationDenial=a,exports.linkProject=i,exports.getRegistryAccess=c,exports.listRegistryAccessTokens=u,exports.createRegistryAccessToken=l,exports.rotateRegistryAccessToken=d,exports.readViewerAccount=y;const e=require("./console-api"),t=require("./project-link-manifest");async function r(e){const t=await e.request("/v1/projects/editions");if(!Array.isArray(t))throw x("the Project list");return t.map(e=>{const t=g(e,"a Project");return{id:v(t.id,"a Project id"),name:v(t.name,"a Project name"),edition:E(t.edition,exports.PROJECT_EDITIONS,"a Project edition"),source:A(t.source,["override","subscription","evaluation","none"],"a Project access source")}})}async function o(e,t){const r=g(await e.request("/v1/projects",{method:"POST",body:{name:t.name},...t.idempotencyKey?{headers:{"Idempotency-Key":t.idempotencyKey}}:{}}),"the created Project");return{id:v(r.id,"a Project id"),name:v(r.name,"a Project name"),state:A(r.state,["active","archived"],"a Project state")}}async function n(e,t){const r=g(await e.request(`${f(t)}/evaluation`),"the Evaluation state");if(!Array.isArray(r.offerCodes))throw x("the evaluable Offer list");return{startState:A(r.startState,["available","already_active","project_inactive","account_evaluation_active","rolling_window"],"an Evaluation start state"),nextEligibleAt:null===r.nextEligibleAt?null:v(r.nextEligibleAt,"a next eligible time"),offerCodes:r.offerCodes.filter(e=>exports.EVALUATION_OFFER_CODES.includes(e))}}async function s(e,t,r){const o=g(await e.request(`${f(t)}/evaluation`,{method:"POST",body:{offerCode:r}}),"the Evaluation result"),n=g(o.evaluation,"the Evaluation");return{outcome:A(o.outcome,["started","existing"],"an Evaluation outcome"),offerCode:v(n.offerCode,"an Evaluation offer"),expiresAt:v(n.expiresAt,"an Evaluation expiry")}}function a(t){var r,o;if(!(t instanceof e.ConsoleApiError)||"evaluation.start_denied"!==t.code)return;const n=null===(r=t.body)||void 0===r?void 0:r.reason,s=null===(o=t.body)||void 0===o?void 0:o.nextEligibleAt;return{message:t.message,..."string"==typeof n?{reason:n}:{},..."string"==typeof s?{nextEligibleAt:s}:{}}}async function i(e,r){return(0,t.parseProjectLinkManifest)(await e.request(`${f(r)}/link`,{method:"POST"}))}async function c(e,t){const r=g(await e.request(`${f(t)}/registry-access`),"the Registry access configuration");return{registryUrl:v(r.registryUrl,"a Registry URL"),scope:v(r.scope,"a Registry scope")}}async function u(e,t){const r=await e.request(`${f(t)}/registry-access-tokens`);if(!Array.isArray(r))throw x("the Registry Access Token list");return r.map(e=>p(e))}async function l(e,t,r){return m(await e.request(`${f(t)}/registry-access-tokens`,{method:"POST",body:{name:r}}))}async function d(e,t,r){return m(await e.request(`${f(t)}/registry-access-tokens/${encodeURIComponent(r)}/rotate`,{method:"POST"}))}async function y(e){const t=g(await e.request("/v1/me"),"the Console viewer");if(!t.customerAccount)return;const r=g(t.customerAccount,"the Customer Account");return{id:v(r.id,"a Customer Account id"),name:v(r.name,"a Customer Account name")}}function f(e){return`/v1/projects/${encodeURIComponent(e)}`}function p(e){const t=g(e,"a Registry Access Token");return{id:v(t.id,"a Registry Access Token id"),name:v(t.name,"a Registry Access Token name"),state:A(t.state,["active","expired","revoked"],"a token state")}}function m(e){const t=g(e,"the issued Registry Access Token");return{...p(e),token:v(t.token,"a Registry Access Token secret")}}function g(e,t){if(!e||"object"!=typeof e||Array.isArray(e))throw x(t);return e}function v(e,t){if("string"!=typeof e||0===e.length)throw x(t);return e}function A(e,t,r){if("string"!=typeof e||!t.includes(e))throw x(r);return e}function E(e,t,r){return null==e?null:A(e,t,r)}function x(e){return new Error(`Vendure Console returned ${e} in an unexpected shape.`)}exports.PROJECT_EDITIONS=["starter","growth","scale","enterprise"],exports.EVALUATION_OFFER_CODES=["starter","growth","scale"];