@oxyhq/core 3.0.0 → 3.2.0

package/src/mixins/OxyServices.applications.ts

@@ -58,12 +58,22 @@ export interface Application {
   webhookUrl?: string;
   devWebhookUrl?: string;
   createdByUserId: string;
+  /**
+   * The workspace this application belongs to (workspace `_id`), or `null` for
+   * applications not owned by a workspace. Used by the console to scope apps to
+   * a workspace and to branch on workspace-derived access.
+   */
+  workspaceId: string | null;
   createdAt: string;
   updatedAt: string;
   /**
    * The calling user's own membership in this application, embedded by the API
    * on list (`GET /applications`) and detail (`GET /applications/:appId`)
    * responses. Use `callerMembership.permissions` to gate UI affordances.
+   *
+   * When the caller's access is derived from a workspace membership rather than
+   * a direct application membership, the API returns a synthetic membership
+   * with `source: 'workspace'` and `_id: null`.
    */
   callerMembership?: ApplicationMember;
 }
@@ -73,7 +83,11 @@ export interface Application {
  * on the server at write time.
  */
 export interface ApplicationMember {
-  _id: string;
+  /**
+   * The membership's Mongo `_id`. `null` for a synthetic, workspace-derived
+   * membership (see {@link Application.callerMembership} and `source`).
+   */
+  _id: string | null;
   applicationId: string;
   userId: string;
   role: ApplicationRole;
@@ -81,6 +95,13 @@ export interface ApplicationMember {
   invitedByUserId?: string;
   joinedAt?: string;
   status: ApplicationMemberStatus;
+  /**
+   * Origin of this membership. When `'workspace'`, the membership is synthetic
+   * and derived from the caller's workspace membership rather than a direct
+   * application membership (in which case `_id` is `null`). Absent or any other
+   * value indicates a direct application membership.
+   */
+  source?: 'workspace';
   createdAt: string;
   updatedAt: string;
 }
@@ -100,11 +121,49 @@ export interface ApplicationCredential {
   status: ApplicationCredentialStatus;
   lastUsedAt?: string;
   expiresAt?: string;
+  /**
+   * Audit link to the credential this one was rotated FROM. Populated by the
+   * API on credentials created via rotation; absent on original credentials.
+   */
+  rotatedFromCredentialId?: string;
   createdByUserId: string;
   createdAt: string;
   updatedAt: string;
 }
 
+/**
+ * Sanitized, PUBLIC application identity returned by the API when resolving a
+ * cross-app/OAuth client to a registered {@link Application}.
+ *
+ * Unlike {@link Application}, this shape carries NO sensitive or membership
+ * fields — it is safe to display unauthenticated in consent/authorize screens
+ * and device-flow approval UIs. The API resolves a `client_id` (OAuth
+ * credential public key) to the owning application and projects only the
+ * fields below. `id` is the application's `_id` as a string.
+ */
+export interface PublicApplication {
+  /** The application's Mongo `_id` as a string. */
+  id: string;
+  /** Human-readable application name shown to the user. */
+  name: string;
+  /** Optional short description of what the application does. */
+  description?: string;
+  /** Optional icon URL for the application. */
+  icon?: string;
+  /** Optional public website/homepage URL for the application. */
+  websiteUrl?: string;
+  /** Application classification (set by Oxy platform staff). */
+  type: ApplicationType;
+  /** Whether the application is an officially endorsed Oxy application. */
+  isOfficial: boolean;
+  /** Whether the application is an internal Oxy ecosystem application. */
+  isInternal: boolean;
+  /** OAuth scopes the application is configured to request. */
+  scopes: string[];
+  /** Optional display name of the developer/owner organisation. */
+  developerName?: string;
+}
+
 /** Input accepted by `createApplication`. Staff-only fields are not settable here. */
 export interface CreateApplicationInput {
   name: string;
@@ -113,6 +172,11 @@ export interface CreateApplicationInput {
   icon?: string;
   redirectUris?: string[];
   scopes?: string[];
+  /**
+   * Optional workspace `_id` to create the app in. Omitted → API defaults to
+   * the caller's personal workspace.
+   */
+  workspaceId?: string;
 }
 
 /** Input accepted by `updateApplication`. Staff-only fields are not settable here. */
@@ -152,12 +216,25 @@ export interface CreateApplicationCredentialInput {
   scopes?: string[];
 }
 
-/** Result of creating or rotating a credential — `secret` is returned ONCE. */
+/** Result of creating a credential — `secret` is returned ONCE. */
 export interface ApplicationCredentialWithSecret {
   credential: ApplicationCredential;
   secret: string;
 }
 
+/**
+ * Result of rotating a credential. Extends the create result with audit fields:
+ * the new plaintext `secret` is returned ONCE, plus `rotatedFrom` (the previous
+ * credential's `credentialId`) and `graceExpiresAt` (ISO string marking when the
+ * old credential stops being honoured during the rotation grace window).
+ */
+export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
+  /** The previous credential's `credentialId` that this rotation supersedes. */
+  rotatedFrom: string;
+  /** ISO timestamp at which the rotated-from credential's grace window ends. */
+  graceExpiresAt: string;
+}
+
 /** Time window for application usage statistics. */
 export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
 
@@ -204,14 +281,47 @@ export function OxyServicesApplicationsMixin<T extends typeof OxyServicesBase>(B
       super(...(args as [any]));
     }
 
+    /**
+     * Resolve an OAuth client identifier to the owning application's PUBLIC
+     * identity. No authentication required — the API returns only sanitized,
+     * display-safe metadata ({@link PublicApplication}). Use this to render the
+     * requesting application's name/icon in consent, authorize, and device-flow
+     * approval UIs before any session exists.
+     *
+     * @param clientId - The OAuth `client_id` (an active credential's public
+     *   key). URL-encoded before being placed in the path.
+     */
+    async getPublicApplication(clientId: string): Promise<PublicApplication> {
+      try {
+        const res = await this.makeRequest<{ application: PublicApplication }>(
+          'GET',
+          `/auth/oauth/client/${encodeURIComponent(clientId)}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.application;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * List applications the current user is an active member of.
+     *
+     * @param workspaceId - Optional workspace `_id` to scope the listing to
+     *   applications belonging to that workspace. When provided it is appended
+     *   as a `workspaceId` query parameter (URL-encoded). The query string is
+     *   part of the request path, so the response cache keys on it
+     *   automatically — scoped and unscoped lists never collide.
      */
-    async getApplications(): Promise<Application[]> {
+    async getApplications(workspaceId?: string): Promise<Application[]> {
       try {
+        const path = workspaceId
+          ? `/applications?workspaceId=${encodeURIComponent(workspaceId)}`
+          : '/applications';
         const res = await this.makeRequest<{ applications?: Application[] }>(
           'GET',
-          '/applications',
+          path,
           undefined,
           { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
         );
@@ -445,16 +555,18 @@ export function OxyServicesApplicationsMixin<T extends typeof OxyServicesBase>(B
 
     /**
      * Rotate a credential's secret. The new plaintext `secret` is returned
-     * exactly ONCE.
+     * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
+     * credentialId) and `graceExpiresAt` (ISO string for the grace window during
+     * which the old credential is still honoured).
      * @param applicationId - The application's Mongo `_id`.
      * @param credentialId - The credential's Mongo `_id`.
      */
     async rotateApplicationCredential(
       applicationId: string,
       credentialId: string,
-    ): Promise<ApplicationCredentialWithSecret> {
+    ): Promise<RotateApplicationCredentialResult> {
       try {
-        return await this.makeRequest<ApplicationCredentialWithSecret>(
+        return await this.makeRequest<RotateApplicationCredentialResult>(
           'POST',
           `/applications/${applicationId}/credentials/${credentialId}/rotate`,
           undefined,

package/src/mixins/OxyServices.utility.ts

@@ -18,6 +18,7 @@ interface JwtPayload {
   sessionId?: string;
   type?: string;
   appId?: string;
+  credentialId?: string;
   appName?: string;
   scopes?: string[];
   aud?: string | string[];
@@ -61,6 +62,13 @@ export interface ServiceApp {
   appId: string;
   appName: string;
   scopes: string[];
+  /**
+   * The credentialId of the specific service credential that minted this token.
+   * Carried by newer service-token JWTs alongside `appId`; absent on tokens
+   * issued before credential-level audit linking. Use for per-credential audit
+   * trails and rotation alignment (GitHub #215).
+   */
+  credentialId?: string;
 }
 
 /**
@@ -618,6 +626,9 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
               appId,
               appName: decoded.appName || 'unknown',
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
+              ...(typeof decoded.credentialId === 'string' && decoded.credentialId.length > 0
+                ? { credentialId: decoded.credentialId }
+                : {}),
             };
 
             if (debug) {

package/src/mixins/OxyServices.workspaces.ts

@@ -0,0 +1,309 @@
+/**
+ * Workspaces Methods Mixin
+ *
+ * Provides methods for managing Oxy workspaces and their members via the
+ * `/workspaces` API. A workspace is a multi-user container that owns
+ * applications and other resources: membership (with a role) grants
+ * permissions. A `personal` workspace is created implicitly for every user;
+ * `team` workspaces are created explicitly and can invite additional members.
+ *
+ * Reference workspaces by their Mongo `_id` and members by their member `_id`.
+ * Never by name or slug.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+import { CACHE_TIMES } from './mixinHelpers';
+
+/** Role a member holds within a workspace. */
+export type WorkspaceRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+/** Workspace classification. A `personal` workspace is implicit per user. */
+export type WorkspaceType = 'personal' | 'team';
+
+/** Lifecycle status of a workspace. */
+export type WorkspaceStatus = 'active' | 'deleted';
+
+/** Membership lifecycle status. */
+export type WorkspaceMemberStatus = 'active' | 'invited' | 'removed';
+
+/**
+ * Client-facing WorkspaceMember shape. `permissions` is derived from `role`
+ * on the server at write time.
+ */
+export interface WorkspaceMember {
+  _id: string;
+  workspaceId: string;
+  userId: string;
+  role: WorkspaceRole;
+  permissions: string[];
+  invitedByUserId?: string | null;
+  joinedAt?: string | null;
+  status: WorkspaceMemberStatus;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Client-facing Workspace shape returned by the `/workspaces` API. Mirrors the
+ * server `Workspace` model with `_id` as a string and dates serialized to ISO
+ * strings.
+ */
+export interface Workspace {
+  _id: string;
+  name: string;
+  slug: string;
+  type: WorkspaceType;
+  description?: string | null;
+  icon?: string | null;
+  ownerId: string;
+  status: WorkspaceStatus;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * The calling user's own membership in this workspace, embedded by the API
+   * on list (`GET /workspaces`) and detail (`GET /workspaces/:id`) responses.
+   * Use `callerMembership.permissions` to gate UI affordances.
+   */
+  callerMembership?: WorkspaceMember | null;
+}
+
+/** Input accepted by `createWorkspace`. */
+export interface CreateWorkspaceInput {
+  name: string;
+  description?: string;
+  icon?: string;
+}
+
+/** Input accepted by `updateWorkspace`. */
+export interface UpdateWorkspaceInput {
+  name?: string;
+  description?: string | null;
+  icon?: string | null;
+}
+
+/** Input accepted by `inviteWorkspaceMember`. The owner role cannot be invited. */
+export interface InviteWorkspaceMemberInput {
+  userId: string;
+  role: Exclude<WorkspaceRole, 'owner'>;
+}
+
+/** Input accepted by `updateWorkspaceMember`. The owner role cannot be assigned. */
+export interface UpdateWorkspaceMemberInput {
+  role: Exclude<WorkspaceRole, 'owner'>;
+}
+
+/** Input accepted by `transferWorkspaceOwnership`. */
+export interface TransferWorkspaceOwnershipInput {
+  userId: string;
+}
+
+/** Result of a delete/remove/transfer operation. */
+export interface WorkspaceSuccessResult {
+  success: boolean;
+}
+
+export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * List workspaces the current user is an active member of.
+     */
+    async getWorkspaces(): Promise<Workspace[]> {
+      try {
+        const res = await this.makeRequest<{ workspaces?: Workspace[] }>(
+          'GET',
+          '/workspaces',
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.workspaces ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Create a new team workspace. The caller becomes its `owner`.
+     * @param data - Workspace configuration.
+     */
+    async createWorkspace(data: CreateWorkspaceInput): Promise<Workspace> {
+      try {
+        const res = await this.makeRequest<{ workspace: Workspace }>(
+          'POST',
+          '/workspaces',
+          data,
+          { cache: false },
+        );
+        return res.workspace;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Fetch a single workspace by id.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     */
+    async getWorkspace(workspaceId: string): Promise<Workspace> {
+      try {
+        const res = await this.makeRequest<{ workspace: Workspace }>(
+          'GET',
+          `/workspaces/${encodeURIComponent(workspaceId)}`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.LONG },
+        );
+        return res.workspace;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Update a workspace's mutable fields.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     * @param data - Subset of updatable fields.
+     */
+    async updateWorkspace(
+      workspaceId: string,
+      data: UpdateWorkspaceInput,
+    ): Promise<Workspace> {
+      try {
+        const res = await this.makeRequest<{ workspace: Workspace }>(
+          'PATCH',
+          `/workspaces/${encodeURIComponent(workspaceId)}`,
+          data,
+          { cache: false },
+        );
+        return res.workspace;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Soft-delete a workspace (owner only).
+     * @param workspaceId - The workspace's Mongo `_id`.
+     */
+    async deleteWorkspace(workspaceId: string): Promise<WorkspaceSuccessResult> {
+      try {
+        return await this.makeRequest<WorkspaceSuccessResult>(
+          'DELETE',
+          `/workspaces/${encodeURIComponent(workspaceId)}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * List members of a workspace.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     */
+    async getWorkspaceMembers(workspaceId: string): Promise<WorkspaceMember[]> {
+      try {
+        const res = await this.makeRequest<{ members?: WorkspaceMember[] }>(
+          'GET',
+          `/workspaces/${encodeURIComponent(workspaceId)}/members`,
+          undefined,
+          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
+        );
+        return res.members ?? [];
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Add a member to a workspace.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     * @param data - Target user id and role (never `owner`).
+     */
+    async inviteWorkspaceMember(
+      workspaceId: string,
+      data: InviteWorkspaceMemberInput,
+    ): Promise<WorkspaceMember> {
+      try {
+        const res = await this.makeRequest<{ member: WorkspaceMember }>(
+          'POST',
+          `/workspaces/${encodeURIComponent(workspaceId)}/members`,
+          data,
+          { cache: false },
+        );
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Change a member's role.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     * @param data - New role (never `owner`).
+     */
+    async updateWorkspaceMember(
+      workspaceId: string,
+      memberId: string,
+      data: UpdateWorkspaceMemberInput,
+    ): Promise<WorkspaceMember> {
+      try {
+        const res = await this.makeRequest<{ member: WorkspaceMember }>(
+          'PATCH',
+          `/workspaces/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(memberId)}`,
+          data,
+          { cache: false },
+        );
+        return res.member;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Remove a member from a workspace.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     * @param memberId - The member's Mongo `_id`.
+     */
+    async removeWorkspaceMember(
+      workspaceId: string,
+      memberId: string,
+    ): Promise<WorkspaceSuccessResult> {
+      try {
+        return await this.makeRequest<WorkspaceSuccessResult>(
+          'DELETE',
+          `/workspaces/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(memberId)}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Transfer ownership of a workspace to another member (owner only).
+     * Demotes the current owner and promotes the target to `owner`.
+     * @param workspaceId - The workspace's Mongo `_id`.
+     * @param data - Target user id.
+     */
+    async transferWorkspaceOwnership(
+      workspaceId: string,
+      data: TransferWorkspaceOwnershipInput,
+    ): Promise<WorkspaceSuccessResult> {
+      try {
+        return await this.makeRequest<WorkspaceSuccessResult>(
+          'POST',
+          `/workspaces/${encodeURIComponent(workspaceId)}/transfer-ownership`,
+          data,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/index.ts

@@ -18,6 +18,7 @@ import { OxyServicesPaymentMixin } from './OxyServices.payment';
 import { OxyServicesKarmaMixin } from './OxyServices.karma';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesApplicationsMixin } from './OxyServices.applications';
+import { OxyServicesWorkspacesMixin } from './OxyServices.workspaces';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -51,6 +52,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesApplicationsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>>
@@ -115,6 +117,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesKarmaMixin,
     OxyServicesAssetsMixin,
     OxyServicesApplicationsMixin,
+    OxyServicesWorkspacesMixin,
     OxyServicesLocationMixin,
     OxyServicesAnalyticsMixin,
     OxyServicesDevicesMixin,

package/src/models/interfaces.ts

@@ -17,6 +17,15 @@ export interface OxyConfig {
   sessionBaseUrl?: string;
   authWebUrl?: string;
   authRedirectUri?: string;
+  /**
+   * The app's Oxy OAuth client id (ApplicationCredential publicKey).
+   *
+   * Identifies this app in OAuth authorize / consent flows (issue #214). Purely
+   * declarative: the SDK stores it on `OxyServices.config.clientId` for later
+   * OAuth-authorize use. It is unrelated to the cross-domain `/sso?client_id=…`
+   * bounce (which uses the RP origin, not this registered client id).
+   */
+  clientId?: string;
   // Performance & caching options
   enableCache?: boolean;
   cacheTTL?: number; // Cache TTL in milliseconds (default: 5 minutes)