@kmlckj/licos-platform-sdk 0.6.9 → 0.8.0

package/README.md

@@ -119,5 +119,58 @@ const results = await knowledge.search('How do I reset my password?', {
 });
 ```
 
-The browser entry does not export knowledge helpers because runtime tokens must
-not be bundled into public frontend code.
+The browser entry does not export knowledge helpers because runtime tokens must
+not be bundled into public frontend code.
+
+## OAuth2 Application Management
+
+OAuth2 management is available only from trusted Node runtime code. It uses the
+current project owner's platform identity and is not exported by the browser
+entry.
+
+```js
+import { oauth } from '@kmlckj/licos-platform-sdk';
+
+const apps = await oauth.listApps();
+const app = await oauth.ensureProjectApp({
+  appId: apps.list?.[0]?.id,
+  name: 'Project login',
+  loginAudience: 'ALL',
+  redirectUriConfigs: [
+    { environment: 'prod', redirectUri: 'https://app.example/auth/callback' },
+  ],
+});
+```
+
+`ensureProjectApp` requires an explicit login audience and at least one
+callback. Store only public PKCE settings in project configuration; never put
+the returned client secret or a platform user token in browser code.
+
+## OAuth2 Project Runtime
+
+Project server routes use `oauthRuntime` for Authorization Code + PKCE. The
+runtime module reads `config/licos-oauth.json`; it is intentionally absent from
+the browser entry.
+
+```js
+import { oauthRuntime } from '@kmlckj/licos-platform-sdk';
+
+const config = await oauthRuntime.loadConfig();
+const attempt = oauthRuntime.createAuthorizationRequest(config, {
+  redirectUri: 'https://app.example/api/auth/licos/callback',
+});
+
+// Persist a hash of attempt.state plus codeVerifier, redirectUri and expiresAt
+// in a one-time server-side record before redirecting the browser.
+
+const completed = await oauthRuntime.completeAuthorization(config, {
+  code,
+  redirectUri: stored.redirectUri,
+  codeVerifier: stored.codeVerifier,
+});
+```
+
+`completeAuthorization` returns platform tokens and userinfo to trusted server
+code. Map `completed.user.sub` to the project's account, create the project's
+own session, then revoke tokens unless the application explicitly needs
+delegated platform API access. Never return these tokens to the browser.

package/dist/index.d.ts

@@ -26,7 +26,166 @@ export interface RuntimeConfig {
 }
 
 export function runtimeConfig(options?: { environmentOverrideEnv?: string }): Promise<RuntimeConfig>;
-export function authHeaders(config: RuntimeConfig, contentType?: string): Record<string, string>;
+export function authHeaders(config: RuntimeConfig, contentType?: string): Record<string, string>;
+
+export type OAuthLoginAudience = 'ALL' | 'OWNER_TENANT';
+
+export interface OAuthRedirectUriConfig {
+  environment?: 'dev' | 'prod';
+  redirectUri: string;
+}
+
+export interface OAuthApp {
+  id: string;
+  tenantId?: string;
+  appCode?: string;
+  name?: string;
+  description?: string;
+  clientId?: string;
+  loginAudience?: OAuthLoginAudience;
+  redirectUris?: string[];
+  redirectUriConfigs?: OAuthRedirectUriConfig[];
+  allowedScopes?: string[];
+  secret?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+
+export interface OAuthAppList {
+  list?: OAuthApp[];
+  total?: number;
+  page?: number;
+  pageSize?: number;
+  hasNext?: boolean;
+}
+
+export interface CreateOAuthAppOptions {
+  description?: string;
+  appCode?: string;
+  app_code?: string;
+  loginAudience?: OAuthLoginAudience;
+  login_audience?: OAuthLoginAudience;
+  redirectUriConfigs?: OAuthRedirectUriConfig[];
+  redirect_uri_configs?: OAuthRedirectUriConfig[];
+  redirectUris?: string[];
+  redirect_uris?: string[];
+  allowedScopes?: string[];
+  allowed_scopes?: string[];
+  appType?: string;
+  app_type?: string;
+  consentRequired?: boolean;
+  consent_required?: boolean;
+}
+
+export interface EnsureProjectOAuthAppOptions extends CreateOAuthAppOptions {
+  name: string;
+  loginAudience: OAuthLoginAudience;
+  appId?: string;
+  app_id?: string;
+  redirectUriConfigs: OAuthRedirectUriConfig[];
+}
+
+export function listOAuthApps(options?: { page?: number; pageSize?: number }): Promise<OAuthAppList>;
+export function getOAuthApp(appId: string): Promise<OAuthApp>;
+export function createOAuthApp(name: string, options?: CreateOAuthAppOptions): Promise<OAuthApp>;
+export function updateOAuthApp(appId: string, changes?: Record<string, unknown>): Promise<OAuthApp>;
+export function deleteOAuthApp(appId: string): Promise<void>;
+export function setOAuthAppEnabled(appId: string, enabled: boolean): Promise<OAuthApp>;
+export function rotateOAuthAppSecret(appId: string): Promise<OAuthApp>;
+export function listOAuthGrants(appId: string): Promise<Array<Record<string, unknown>>>;
+export function revokeOAuthGrant(grantId: string): Promise<void>;
+export function findOAuthAppByCode(appCode: string, options?: { pageSize?: number }): Promise<OAuthApp | null>;
+export function ensureProjectOAuthApp(options: EnsureProjectOAuthAppOptions): Promise<OAuthApp>;
+
+export const oauth: {
+  listApps: typeof listOAuthApps;
+  getApp: typeof getOAuthApp;
+  createApp: typeof createOAuthApp;
+  updateApp: typeof updateOAuthApp;
+  deleteApp: typeof deleteOAuthApp;
+  setEnabled: typeof setOAuthAppEnabled;
+  rotateSecret: typeof rotateOAuthAppSecret;
+  listGrants: typeof listOAuthGrants;
+  revokeGrant: typeof revokeOAuthGrant;
+  findAppByCode: typeof findOAuthAppByCode;
+  ensureProjectApp: typeof ensureProjectOAuthApp;
+};
+
+export class OAuthProtocolError extends ApiError {
+  error?: string;
+}
+
+export interface OAuthRuntimeConfig {
+  clientId: string;
+  publicBaseUrl: string;
+  scopes: readonly string[];
+  redirectUris: readonly string[];
+  endpoints: Readonly<Record<string, string>>;
+  appId?: string;
+  appCode?: string;
+  loginAudience?: OAuthLoginAudience;
+}
+
+export interface OAuthAuthorizationRequest {
+  authorizationUrl: string;
+  state: string;
+  codeVerifier: string;
+  redirectUri: string;
+  expiresAt: number;
+}
+
+export interface OAuthTokenResponse {
+  access_token: string;
+  token_type?: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+  id_token?: string;
+  [key: string]: unknown;
+}
+
+export function loadOAuthRuntimeConfig(options?: { configPath?: string }): Promise<OAuthRuntimeConfig>;
+export function createOAuthAuthorizationRequest(
+  config: OAuthRuntimeConfig,
+  options: {
+    redirectUri: string;
+    scopes?: string[];
+    state?: string;
+    codeVerifier?: string;
+    ttlSeconds?: number;
+    now?: number;
+  },
+): OAuthAuthorizationRequest;
+export function exchangeOAuthAuthorizationCode(
+  config: OAuthRuntimeConfig,
+  options: { code: string; redirectUri: string; codeVerifier: string },
+): Promise<OAuthTokenResponse>;
+export function refreshOAuthAccessToken(
+  config: OAuthRuntimeConfig,
+  options: { refreshToken: string; scopes?: string[] },
+): Promise<OAuthTokenResponse>;
+export function getOAuthUserInfo(
+  config: OAuthRuntimeConfig,
+  options: { accessToken: string },
+): Promise<Record<string, unknown>>;
+export function revokeOAuthToken(
+  config: OAuthRuntimeConfig,
+  options: { token: string; tokenTypeHint?: 'access_token' | 'refresh_token' | string },
+): Promise<void>;
+export function completeOAuthAuthorization(
+  config: OAuthRuntimeConfig,
+  options: { code: string; redirectUri: string; codeVerifier: string },
+): Promise<{ tokens: OAuthTokenResponse; user: Record<string, unknown> }>;
+
+export const oauthRuntime: {
+  loadConfig: typeof loadOAuthRuntimeConfig;
+  createAuthorizationRequest: typeof createOAuthAuthorizationRequest;
+  exchangeAuthorizationCode: typeof exchangeOAuthAuthorizationCode;
+  refreshAccessToken: typeof refreshOAuthAccessToken;
+  getUserInfo: typeof getOAuthUserInfo;
+  revokeToken: typeof revokeOAuthToken;
+  completeAuthorization: typeof completeOAuthAuthorization;
+};
 
 export const DataSourceType: {
   TEXT: 0;

package/dist/index.js

@@ -1 +1 @@
-export{PlatformSdkError,ConfigurationError,ApiError}from"./shared.js";export{runtimeConfig,authHeaders}from"./runtime.js";export*from"./database.js";export*from"./knowledge.js";export*from"./storage.js";export{studioDatabase}from"./studio-database.js";
+export{PlatformSdkError,ConfigurationError,ApiError}from"./shared.js";export{runtimeConfig,authHeaders}from"./runtime.js";export*from"./database.js";export*from"./knowledge.js";export*from"./oauth.js";export*from"./oauth-runtime.js";export*from"./storage.js";export{studioDatabase}from"./studio-database.js";

package/dist/oauth-runtime.js

@@ -0,0 +1 @@
+import{createHash as e,randomBytes as t}from"node:crypto";import{readFile as r}from"node:fs/promises";import o from"node:path";import{ApiError as n}from"./shared.js";const i=["authorization","token","userinfo","revoke"],s=/^[A-Za-z0-9._~-]{43,128}$/;export class OAuthProtocolError extends n{constructor(e,t={}){super(e,t),this.error=t.error}}function c(e,t){const r=String(e||"").trim();let o;try{o=new URL(r)}catch{throw new TypeError(`${t} must be an absolute http(s) URL`)}if(!["http:","https:"].includes(o.protocol))throw new TypeError(`${t} must be an absolute http(s) URL`);if(o.hash)throw new TypeError(`${t} must not contain a fragment`);return r}function a(e){return new URL(e).origin.toLowerCase()}function u(e,t,r){const o=String(t||"").trim();if(!o)throw new TypeError(`OAuth endpoint is missing: ${r}`);const n=c(new URL(o,`${e}/`).toString(),`endpoints.${r}`);if(a(n)!==a(e))throw new TypeError(`OAuth endpoint ${r} must use the same origin as publicBaseUrl`);return n}function h(e){return!(!e||"object"!=typeof e)&&(Array.isArray(e)?e.some(h):Object.entries(e).some(([e,t])=>e.toLowerCase().replaceAll("_","").includes("secret")||h(t)))}export async function loadOAuthRuntimeConfig({configPath:e}={}){const t=o.resolve(process.env.LICOS_PROJECT_PATH||process.cwd()),n=o.resolve(e||o.join(t,"config/licos-oauth.json"));let s;try{s=JSON.parse(await r(n,"utf8"))}catch(e){if("ENOENT"===e?.code)throw new TypeError(`OAuth config not found: ${n}`);if(e instanceof SyntaxError)throw new TypeError(`OAuth config is not valid JSON: ${n}`);throw e}if(!s||"object"!=typeof s||Array.isArray(s))throw new TypeError("OAuth config must be a JSON object");if(h(s))throw new TypeError("OAuth config must not contain client secret fields");if("licos-oauth2"!==s.provider)throw new TypeError("OAuth config provider must be licos-oauth2");if(!0!==s.pkce)throw new TypeError("OAuth config must enable PKCE");const a=String(s.clientId||"").trim();if(!a)throw new TypeError("OAuth config is missing clientId");const p=c(s.publicBaseUrl,"publicBaseUrl").replace(/\/$/,"");if(!Array.isArray(s.scopes)||0===s.scopes.length||s.scopes.some(e=>!String(e).trim()))throw new TypeError("OAuth config scopes must be a non-empty string array");if(!Array.isArray(s.redirectUriConfigs)||0===s.redirectUriConfigs.length)throw new TypeError("OAuth config redirectUriConfigs must not be empty");const f=[...new Set(s.scopes.map(e=>String(e).trim()))],d=[...new Set(s.redirectUriConfigs.map(e=>c(e?.redirectUri,"redirectUri")))];if(!s.endpoints||"object"!=typeof s.endpoints||Array.isArray(s.endpoints))throw new TypeError("OAuth config endpoints must be an object");const l=Object.fromEntries(Object.entries(s.endpoints).map(([e,t])=>[e,u(p,t,e)]));for(const e of i)if(!l[e])throw new TypeError(`OAuth endpoint is missing: ${e}`);return Object.freeze({clientId:a,publicBaseUrl:p,scopes:Object.freeze(f),redirectUris:Object.freeze(d),endpoints:Object.freeze(l),appId:String(s.appId||"").trim()||void 0,appCode:String(s.appCode||"").trim()||void 0,loginAudience:String(s.loginAudience||"").trim()||void 0})}function p(e,t){const r=c(t,"redirectUri");if(!e.redirectUris.includes(r))throw new TypeError("redirectUri is not configured for this OAuth application");return r}function f(e){if(!s.test(e))throw new TypeError("codeVerifier must be 43-128 RFC 7636 unreserved characters");return e}function d(e,t){const r=[...new Set((t||e.scopes).map(e=>String(e).trim()).filter(Boolean))];if(0===r.length)throw new TypeError("at least one OAuth scope is required");const o=r.filter(t=>!e.scopes.includes(t));if(o.length)throw new TypeError(`OAuth scopes are not configured: ${o.sort().join(", ")}`);return r}export function createOAuthAuthorizationRequest(r,o){const n=p(r,o?.redirectUri),i=d(r,o?.scopes),s=String(o?.state||t(32).toString("base64url")).trim();if(!s)throw new TypeError("state is required");const c=f(o?.codeVerifier||t(64).toString("base64url")),a=o?.ttlSeconds??600;if(!Number.isInteger(a)||a<=0)throw new TypeError("ttlSeconds must be a positive integer");const u=e("sha256").update(c,"ascii").digest("base64url"),h=new URL(r.endpoints.authorization);h.search=new URLSearchParams({response_type:"code",client_id:r.clientId,redirect_uri:n,scope:i.join(" "),state:s,code_challenge:u,code_challenge_method:"S256"}).toString();const l=o?.now??Math.floor(Date.now()/1e3);return{authorizationUrl:h.toString(),state:s,codeVerifier:c,redirectUri:n,expiresAt:l+a}}function l(e,t){let r;try{r=e?JSON.parse(e):void 0}catch{r=void 0}const o=r&&"object"==typeof r&&String(r.error||"").trim()||void 0,n=r&&"object"==typeof r&&(r.error_description||r.message||o)||e||"OAuth request failed";return new OAuthProtocolError(String(n),{status:t,error:o,details:r})}async function w(e,{method:t,form:r,accessToken:o,allowEmpty:n=!1}){const i={Accept:"application/json"};let s,c;r&&(s=new URLSearchParams(Object.entries(r).filter(([,e])=>null!=e)).toString(),i["Content-Type"]="application/x-www-form-urlencoded"),o&&(i.Authorization=`Bearer ${o}`);try{c=await fetch(e,{method:t,headers:i,body:s})}catch(e){throw new OAuthProtocolError(`OAuth request failed: ${e?.message||e}`)}const a=await c.text();if(!c.ok)throw l(a,c.status);if(!a){if(n)return;throw new OAuthProtocolError("OAuth response body is empty",{status:c.status})}let u;try{u=JSON.parse(a)}catch{throw new OAuthProtocolError("OAuth response is not valid JSON",{status:c.status})}if(!u||"object"!=typeof u||Array.isArray(u))throw new OAuthProtocolError("OAuth response is not an object",{status:c.status,details:u});if(u.error)throw l(a,c.status);return u}export async function exchangeOAuthAuthorizationCode(e,t){const r=String(t?.code||"").trim();if(!r)throw new TypeError("authorization code is required");const o=p(e,t?.redirectUri),n=f(t?.codeVerifier);return w(e.endpoints.token,{method:"POST",form:{grant_type:"authorization_code",client_id:e.clientId,code:r,redirect_uri:o,code_verifier:n}})}export async function refreshOAuthAccessToken(e,t){const r=String(t?.refreshToken||"").trim();if(!r)throw new TypeError("refreshToken is required");return w(e.endpoints.token,{method:"POST",form:{grant_type:"refresh_token",client_id:e.clientId,refresh_token:r,scope:t?.scopes?d(e,t.scopes).join(" "):void 0}})}export async function getOAuthUserInfo(e,t){const r=String(t?.accessToken||"").trim();if(!r)throw new TypeError("accessToken is required");return w(e.endpoints.userinfo,{method:"GET",accessToken:r})}export async function revokeOAuthToken(e,t){const r=String(t?.token||"").trim();if(!r)throw new TypeError("token is required");await w(e.endpoints.revoke,{method:"POST",form:{client_id:e.clientId,token:r,token_type_hint:t?.tokenTypeHint},allowEmpty:!0})}export async function completeOAuthAuthorization(e,t){const r=await exchangeOAuthAuthorizationCode(e,t),o=String(r.access_token||"").trim();if(!o)throw new OAuthProtocolError("OAuth token response is missing access_token",{details:r});return{tokens:r,user:await getOAuthUserInfo(e,{accessToken:o})}}export const oauthRuntime={loadConfig:loadOAuthRuntimeConfig,createAuthorizationRequest:createOAuthAuthorizationRequest,exchangeAuthorizationCode:exchangeOAuthAuthorizationCode,refreshAccessToken:refreshOAuthAccessToken,getUserInfo:getOAuthUserInfo,revokeToken:revokeOAuthToken,completeAuthorization:completeOAuthAuthorization};

package/dist/oauth.js

@@ -0,0 +1 @@
+import{ApiError as e,ConfigurationError as t}from"./shared.js";import{authHeaders as n,refreshRuntimeConfig as o,runtimeConfig as r,shouldRefreshUserToken as i}from"./runtime.js";const p=Object.freeze({integration_type:"integrationType",app_code:"appCode",logo_url:"logoUrl",app_type:"appType",consent_required:"consentRequired",login_audience:"loginAudience",redirect_uris:"redirectUris",redirect_uri_configs:"redirectUriConfigs",allowed_scopes:"allowedScopes",sso_ticket_ttl_seconds:"ssoTicketTtlSeconds",sso_silent_enabled:"ssoSilentEnabled",allowed_workspace_scope:"allowedWorkspaceScope"});function a(e,t,n={}){const o=new URL(`${e.baseUrl}/api/v1/admin/login-integrations${t}`);for(const[e,t]of Object.entries(n))null!=t&&o.searchParams.set(e,String(t));return o}async function s(t){const n=await t.text(),o=n?JSON.parse(n):null;if(!t.ok)throw new e(o?.message||n||`platform OAuth2 API returned ${t.status}`,{status:t.status,code:"number"==typeof o?.code?o.code:void 0,details:o});if(!o||"object"!=typeof o)return o;if(void 0!==o.code&&0!==o.code||!1===o.success)throw new e(o.message||"platform OAuth2 API failed",{status:t.status,code:"number"==typeof o.code?o.code:void 0,details:o});return o.data}async function c(t,p,{params:c,body:d}={}){let u=await r();for(let e=0;e<2;e+=1)try{const e=await fetch(a(u,p,c),{method:t,headers:n(u),body:void 0===d?void 0:JSON.stringify(d)});return await s(e)}catch(t){if(0===e&&i(t)){u=await o(u);continue}throw t}throw new e("platform OAuth2 API failed")}export async function listOAuthApps({page:e=1,pageSize:t=100}={}){return c("GET","/apps",{params:{page:e,pageSize:t}})}export async function getOAuthApp(e){return c("GET",`/apps/${encodeURIComponent(e)}`)}export async function createOAuthApp(e,t={}){return c("POST","/apps",{body:(n={name:e,description:t.description,appCode:t.appCode??t.app_code,loginAudience:t.loginAudience??t.login_audience??"ALL",redirectUriConfigs:t.redirectUriConfigs??t.redirect_uri_configs,redirectUris:t.redirectUris??t.redirect_uris,allowedScopes:t.allowedScopes??t.allowed_scopes,appType:t.appType??t.app_type,consentRequired:t.consentRequired??t.consent_required},Object.fromEntries(Object.entries(n).filter(([,e])=>null!=e)))});var n}export async function updateOAuthApp(e,t={}){const n=Object.fromEntries(Object.entries(t).map(([e,t])=>[p[e]||e,t]));return c("PUT",`/apps/${encodeURIComponent(e)}`,{body:n})}export async function deleteOAuthApp(e){await c("DELETE",`/apps/${encodeURIComponent(e)}`)}export async function setOAuthAppEnabled(e,t){return c("POST",`/apps/${encodeURIComponent(e)}/${t?"enable":"disable"}`)}export async function rotateOAuthAppSecret(e){return c("POST",`/apps/${encodeURIComponent(e)}/secrets/rotate`)}export async function listOAuthGrants(e){return await c("GET",`/apps/${encodeURIComponent(e)}/grants`)||[]}export async function revokeOAuthGrant(e){await c("DELETE",`/grants/${encodeURIComponent(e)}`)}export async function findOAuthAppByCode(e,{pageSize:t=100}={}){let n=1;for(;;){const o=await listOAuthApps({page:n,pageSize:t})||{},r=(o.list||[]).find(t=>t.appCode===e);if(r)return r;if(!o.hasNext)return null;n+=1}}export async function ensureProjectOAuthApp(e){if(!e||"object"!=typeof e)throw new t("OAuth project app options are required");if(!String(e.name||"").trim())throw new t("name is required");const n=e.loginAudience??e.login_audience;if(!["ALL","OWNER_TENANT"].includes(n))throw new t("loginAudience must be ALL or OWNER_TENANT");const o=e.redirectUriConfigs??e.redirect_uri_configs;if(!Array.isArray(o)||0===o.length)throw new t("redirectUriConfigs must contain at least one callback");if(o.some(e=>!String(e?.redirectUri||"").trim()))throw new t("every redirectUriConfigs item requires redirectUri");const i={name:e.name,login_audience:n,redirect_uri_configs:o,allowed_scopes:e.allowedScopes??e.allowed_scopes??["openid","profile","email"]};if(void 0!==e.description&&null!==e.description&&(i.description=e.description),e.appId??e.app_id){const t=e.appId??e.app_id;return await getOAuthApp(t),updateOAuthApp(t,i)}const p=`project-${(await r()).projectId}`,a=await findOAuthAppByCode(p);return a?updateOAuthApp(a.id,i):createOAuthApp(e.name,{description:e.description,appCode:p,loginAudience:i.login_audience,redirectUriConfigs:i.redirect_uri_configs,allowedScopes:i.allowed_scopes})}export const oauth={listApps:listOAuthApps,getApp:getOAuthApp,createApp:createOAuthApp,updateApp:updateOAuthApp,deleteApp:deleteOAuthApp,setEnabled:setOAuthAppEnabled,rotateSecret:rotateOAuthAppSecret,listGrants:listOAuthGrants,revokeGrant:revokeOAuthGrant,findAppByCode:findOAuthAppByCode,ensureProjectApp:ensureProjectOAuthApp};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kmlckj/licos-platform-sdk",
-  "version": "0.6.9",
+  "version": "0.8.0",
   "description": "LICOS platform SDK package shell for browser and Node runtimes",
   "author": "kmlckj",
   "type": "module",