@stacksjs/hq 0.75.561 → 0.75.568

package/README.md

@@ -109,6 +109,13 @@ for (const { method, path, handler } of hq.routes)
 | `GET /api/cli/connect/{code}` | `200 { status: 'pending' }`; once approved `200 { status: 'approved', project, ingestKey, readKey, dashboardUrl }`, exactly once; otherwise `404 { status: 'expired' }` |
 | `GET /api/v1/usage` | `200 { meter, used, limit, period, state, upgradeUrl }[]`; `401` without a valid `Authorization: Bearer <read key>` |
 
+A service that takes no data from the app, because its product runs inside the
+app, has no keys to hand over. It answers a `LicenseGrant`
+(`{ project, licenseKey, dashboardUrl }`) from `provision` and leaves
+`authenticateReadKey` and `usage` off its adapter. An approved poll then
+carries `licenseKey` in place of the two keys, `routes` holds the two connect
+routes only, and the usage handler answers `404`.
+
 The approve page is the service's own. It calls `hq.describeConnect(code)` to
 show which app is asking and `hq.approveConnect(code, user)` when the signed-in
 user confirms.

package/dist/client.d.ts

@@ -120,7 +120,7 @@ export declare interface HqClient {
  * down or misconfigured must cost that page a panel, not the page. Every
  * failure is a typed `HqUnavailable` value.
  */
-export type HqServiceName = 'bughq' | 'loghq' | 'analyticshq' | 'statushq' | 'commshq';
+export type HqServiceName = 'bughq' | 'loghq' | 'analyticshq' | 'statushq' | 'commshq' | 'reportshq';
 export type HqUnavailableReason = | 'not_configured'
   /** The read key was refused. */
     | 'unauthorized'

package/dist/service.d.ts

@@ -2,6 +2,8 @@ import type { ConnectCodeStore } from './connect-codes';
 import type { MeterPolicy, MeterPolicyName } from './policy';
 import type { UsageReport } from './types';
 export type { UsageReport } from './types';
+/** Whether an approved connect carried a licence rather than keys. */
+export declare function isLicenseGrant(grant: ConnectGrant | LicenseGrant): grant is LicenseGrant;
 /** SHA-256 of a connect code, hex. This, never the code, is what a store holds. */
 export declare function hashConnectCode(code: string): Promise<string>;
 export declare function createHqService<User = unknown>(adapter: HqServiceAdapter<User>, options?: HqServiceOptions): HqService<User>;
@@ -12,6 +14,7 @@ export declare const USAGE_PATH: '/api/v1/usage';
  *
  *   POST /api/cli/connect          -> { code, approveUrl }
  *   GET  /api/cli/connect/{code}   -> pending | { project, ingestKey, readKey, dashboardUrl }
+ *                                     (or { project, licenseKey, dashboardUrl } from a licence-only service)
  *   GET  /api/v1/usage  (read key) -> { meter, used, limit, period, state, upgradeUrl }[]
  *
  * Nothing here knows a router or a database. A service implements
@@ -25,6 +28,19 @@ export declare interface ConnectGrant {
   readKey: string
   dashboardUrl: string
 }
+/**
+ * What a service with no keys hands over instead.
+ *
+ * Some services take no data from the app at all: the product runs inside the
+ * app, and the one thing an account gives it is a licence key. Such a service
+ * answers this from `provision`, leaves `authenticateReadKey` and `usage` off
+ * its adapter, and has no usage route.
+ */
+export declare interface LicenseGrant {
+  project: { id: string, name: string }
+  licenseKey: string
+  dashboardUrl: string
+}
 export declare interface ConnectRequest {
   app: string
 }
@@ -45,9 +61,9 @@ export declare interface HqServiceAdapter<User = unknown> {
   approveUrl: (code: string) => string
   upgradeUrl: string | ((principal: ReadPrincipal) => string)
   codes: ConnectCodeStore
-  provision: (user: User, request: ConnectRequest) => Promise<ConnectGrant>
-  authenticateReadKey: (readKey: string) => Promise<ReadPrincipal | null>
-  usage: (principal: ReadPrincipal) => Promise<MeterReading[]>
+  provision: (user: User, request: ConnectRequest) => Promise<ConnectGrant | LicenseGrant>
+  authenticateReadKey?: (readKey: string) => Promise<ReadPrincipal | null>
+  usage?: (principal: ReadPrincipal) => Promise<MeterReading[]>
 }
 export declare interface HqServiceOptions {
   codeTtlMs?: number
@@ -77,7 +93,8 @@ export declare interface HqService<User = unknown> {
 }
 export type ConnectPollResponse = | { status: 'pending' }
     | { status: 'expired' }
-    | ({ status: 'approved' } & ConnectGrant);
+    | ({ status: 'approved' } & ConnectGrant)
+    | ({ status: 'approved' } & LicenseGrant);
 export type ApproveResult = | { ok: true, project: ConnectGrant['project'] }
     | { ok: false, reason: 'expired' | 'already_approved' }
 export * from './connect-codes';

package/dist/service.js

@@ -1 +1 @@
-import{isPeriod,periodOf}from"./period";import{evaluate}from"./policy";export*from"./connect-codes";export const CONNECT_PATH="/api/cli/connect";export const USAGE_PATH="/api/v1/usage";const encoder=new TextEncoder;const CODE=/^[\w-]{32,128}$/;function base64Url(bytes){let binary="";for(const byte of bytes)binary+=String.fromCharCode(byte);return btoa(binary).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}function fromBase64Url(text){const binary=atob(text.replace(/-/g,"+").replace(/_/g,"/"));const bytes=new Uint8Array(new ArrayBuffer(binary.length));for(let i=0;i<binary.length;i++)bytes[i]=binary.charCodeAt(i);return bytes}export async function hashConnectCode(code){const digest=new Uint8Array(await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-code:${code}`)));return[...digest].map((byte)=>byte.toString(16).padStart(2,"0")).join("")}async function grantKey(code){const material=await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-grant:${code}`));return crypto.subtle.importKey("raw",material,"AES-GCM",false,["encrypt","decrypt"])}async function sealGrant(code,grant){const iv=crypto.getRandomValues(new Uint8Array(new ArrayBuffer(12)));const sealed=new Uint8Array(await crypto.subtle.encrypt({name:"AES-GCM",iv},await grantKey(code),encoder.encode(JSON.stringify(grant))));return`${base64Url(iv)}.${base64Url(sealed)}`}async function openGrant(code,sealed){try{const[iv,body]=sealed.split(".");if(!iv||!body)return null;const plain=await crypto.subtle.decrypt({name:"AES-GCM",iv:fromBase64Url(iv)},await grantKey(code),fromBase64Url(body));return JSON.parse(new TextDecoder().decode(plain))}catch{return null}}function json(body,status=200){return new Response(JSON.stringify(body),{status,headers:{"Content-Type":"application/json","Cache-Control":"no-store"}})}function appName(value){const name=typeof value==="string"?value.replace(/[^\w .-]/g,"").trim().slice(0,64):"";return name||"app"}function pathOf(request){try{return new URL(request.url,"http://localhost").pathname.replace(/\/+$/,"")||"/"}catch{return""}}function bearer(request){const header=request.headers.get("authorization")??"";const match=/^Bearer\s+(\S+)$/i.exec(header.trim());return match?.[1]??null}export function createHqService(adapter,options={}){const now=options.now??(()=>new Date);const ttl=options.codeTtlMs??10*60*1000;async function live(code){if(!CODE.test(code))return null;const codeHash=await hashConnectCode(code);const record=await adapter.codes.find(codeHash);return record&&record.expiresAt>now().getTime()?record:null}async function startConnect(request){let body;try{body=await request.json?.()}catch{}const code=base64Url(crypto.getRandomValues(new Uint8Array(32)));const at=now().getTime();await adapter.codes.prune(at).catch(()=>{});await adapter.codes.create({codeHash:await hashConnectCode(code),app:appName(body?.app),status:"pending",sealedGrant:null,expiresAt:at+ttl});return json({code,approveUrl:adapter.approveUrl(code)},201)}async function describeConnect(code){const record=await live(code);return record&&record.status==="pending"?{app:record.app,expiresAt:record.expiresAt}:null}async function approveConnect(code,user){const record=await live(code);if(!record)return{ok:false,reason:"expired"};if(record.status!=="pending")return{ok:false,reason:"already_approved"};const grant=await adapter.provision(user,{app:record.app});const approved=await adapter.codes.approve(record.codeHash,await sealGrant(code,grant));return approved?{ok:true,project:grant.project}:{ok:false,reason:"already_approved"}}async function pollConnect(request,given){const code=given??request.params?.code??decodeURIComponent(pathOf(request).split("/").pop()??"");const expired=()=>json({status:"expired"},404);const record=await live(code);if(!record)return expired();if(record.status==="pending")return json({status:"pending"});const taken=await adapter.codes.consume(record.codeHash);const grant=taken?.sealedGrant?await openGrant(code,taken.sealedGrant):null;if(!grant)return expired();return json({status:"approved",...grant})}async function usage(request){const key=bearer(request);const principal=key?await adapter.authenticateReadKey(key):null;if(!principal)return json({error:"unauthorized"},401);const upgradeUrl=typeof adapter.upgradeUrl==="function"?adapter.upgradeUrl(principal):adapter.upgradeUrl;const period=periodOf(now());const reports=(await adapter.usage(principal)).map((reading)=>{const evaluation=evaluate(reading.used,reading.limit,reading.policy);return{meter:reading.meter,used:evaluation.used,limit:evaluation.limit,period:isPeriod(reading.period)?reading.period:period,state:evaluation.state,upgradeUrl}});return json(reports)}const routes=[{method:"POST",path:CONNECT_PATH,handler:startConnect},{method:"GET",path:`${CONNECT_PATH}/{code}`,handler:(request)=>pollConnect(request)},{method:"GET",path:USAGE_PATH,handler:usage}];async function handle(request){const method=(request.method??"GET").toUpperCase();const path=pathOf(request);if(method==="POST"&&path===CONNECT_PATH)return startConnect(request);if(method==="GET"&&path.startsWith(`${CONNECT_PATH}/`)&&!path.slice(CONNECT_PATH.length+1).includes("/"))return pollConnect(request,decodeURIComponent(path.slice(CONNECT_PATH.length+1)));if(method==="GET"&&path===USAGE_PATH)return usage(request);return null}return{startConnect,pollConnect,describeConnect,approveConnect,usage,routes,handle}}
+import{isPeriod,periodOf}from"./period";import{evaluate}from"./policy";export*from"./connect-codes";export function isLicenseGrant(grant){return typeof grant.licenseKey==="string"}export const CONNECT_PATH="/api/cli/connect";export const USAGE_PATH="/api/v1/usage";const encoder=new TextEncoder;const CODE=/^[\w-]{32,128}$/;function base64Url(bytes){let binary="";for(const byte of bytes)binary+=String.fromCharCode(byte);return btoa(binary).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}function fromBase64Url(text){const binary=atob(text.replace(/-/g,"+").replace(/_/g,"/"));const bytes=new Uint8Array(new ArrayBuffer(binary.length));for(let i=0;i<binary.length;i++)bytes[i]=binary.charCodeAt(i);return bytes}export async function hashConnectCode(code){const digest=new Uint8Array(await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-code:${code}`)));return[...digest].map((byte)=>byte.toString(16).padStart(2,"0")).join("")}async function grantKey(code){const material=await crypto.subtle.digest("SHA-256",encoder.encode(`hq-connect-grant:${code}`));return crypto.subtle.importKey("raw",material,"AES-GCM",false,["encrypt","decrypt"])}async function sealGrant(code,grant){const iv=crypto.getRandomValues(new Uint8Array(new ArrayBuffer(12)));const sealed=new Uint8Array(await crypto.subtle.encrypt({name:"AES-GCM",iv},await grantKey(code),encoder.encode(JSON.stringify(grant))));return`${base64Url(iv)}.${base64Url(sealed)}`}async function openGrant(code,sealed){try{const[iv,body]=sealed.split(".");if(!iv||!body)return null;const plain=await crypto.subtle.decrypt({name:"AES-GCM",iv:fromBase64Url(iv)},await grantKey(code),fromBase64Url(body));return JSON.parse(new TextDecoder().decode(plain))}catch{return null}}function json(body,status=200){return new Response(JSON.stringify(body),{status,headers:{"Content-Type":"application/json","Cache-Control":"no-store"}})}function appName(value){const name=typeof value==="string"?value.replace(/[^\w .-]/g,"").trim().slice(0,64):"";return name||"app"}function pathOf(request){try{return new URL(request.url,"http://localhost").pathname.replace(/\/+$/,"")||"/"}catch{return""}}function bearer(request){const header=request.headers.get("authorization")??"";const match=/^Bearer\s+(\S+)$/i.exec(header.trim());return match?.[1]??null}export function createHqService(adapter,options={}){const now=options.now??(()=>new Date);const ttl=options.codeTtlMs??10*60*1000;async function live(code){if(!CODE.test(code))return null;const codeHash=await hashConnectCode(code);const record=await adapter.codes.find(codeHash);return record&&record.expiresAt>now().getTime()?record:null}async function startConnect(request){let body;try{body=await request.json?.()}catch{}const code=base64Url(crypto.getRandomValues(new Uint8Array(32)));const at=now().getTime();await adapter.codes.prune(at).catch(()=>{});await adapter.codes.create({codeHash:await hashConnectCode(code),app:appName(body?.app),status:"pending",sealedGrant:null,expiresAt:at+ttl});return json({code,approveUrl:adapter.approveUrl(code)},201)}async function describeConnect(code){const record=await live(code);return record&&record.status==="pending"?{app:record.app,expiresAt:record.expiresAt}:null}async function approveConnect(code,user){const record=await live(code);if(!record)return{ok:false,reason:"expired"};if(record.status!=="pending")return{ok:false,reason:"already_approved"};const grant=await adapter.provision(user,{app:record.app});const approved=await adapter.codes.approve(record.codeHash,await sealGrant(code,grant));return approved?{ok:true,project:grant.project}:{ok:false,reason:"already_approved"}}async function pollConnect(request,given){const code=given??request.params?.code??decodeURIComponent(pathOf(request).split("/").pop()??"");const expired=()=>json({status:"expired"},404);const record=await live(code);if(!record)return expired();if(record.status==="pending")return json({status:"pending"});const taken=await adapter.codes.consume(record.codeHash);const grant=taken?.sealedGrant?await openGrant(code,taken.sealedGrant):null;if(!grant)return expired();return json({status:"approved",...grant})}const metered=Boolean(adapter.authenticateReadKey&&adapter.usage);async function usage(request){if(!adapter.authenticateReadKey||!adapter.usage)return json({error:"not found"},404);const key=bearer(request);const principal=key?await adapter.authenticateReadKey(key):null;if(!principal)return json({error:"unauthorized"},401);const upgradeUrl=typeof adapter.upgradeUrl==="function"?adapter.upgradeUrl(principal):adapter.upgradeUrl;const period=periodOf(now());const reports=(await adapter.usage(principal)).map((reading)=>{const evaluation=evaluate(reading.used,reading.limit,reading.policy);return{meter:reading.meter,used:evaluation.used,limit:evaluation.limit,period:isPeriod(reading.period)?reading.period:period,state:evaluation.state,upgradeUrl}});return json(reports)}const routes=[{method:"POST",path:CONNECT_PATH,handler:startConnect},{method:"GET",path:`${CONNECT_PATH}/{code}`,handler:(request)=>pollConnect(request)},...metered?[{method:"GET",path:USAGE_PATH,handler:usage}]:[]];async function handle(request){const method=(request.method??"GET").toUpperCase();const path=pathOf(request);if(method==="POST"&&path===CONNECT_PATH)return startConnect(request);if(method==="GET"&&path.startsWith(`${CONNECT_PATH}/`)&&!path.slice(CONNECT_PATH.length+1).includes("/"))return pollConnect(request,decodeURIComponent(path.slice(CONNECT_PATH.length+1)));if(metered&&method==="GET"&&path===USAGE_PATH)return usage(request);return null}return{startConnect,pollConnect,describeConnect,approveConnect,usage,routes,handle}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/hq",
   "type": "module",
-  "version": "0.75.561",
+  "version": "0.75.568",
   "description": "What every Stacks HQ service does the same way: usage metering, the connect and usage endpoints, and typed readers.",
   "author": "Chris Breuer",
   "contributors": [