@oxyhq/core 3.0.0 → 3.1.0

package/dist/types/index.d.ts

@@ -33,7 +33,7 @@ export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServic
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
-export type { Application, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
+export type { Application, ApplicationMember, ApplicationCredential, ApplicationRole, ApplicationType, ApplicationStatus, ApplicationMemberStatus, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, InviteApplicationMemberInput, UpdateApplicationMemberInput, TransferApplicationOwnershipInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, ApplicationSuccessResult, } from './mixins/OxyServices.applications';
 export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers';
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';

package/dist/types/mixins/OxyServices.applications.d.ts

@@ -89,6 +89,11 @@ 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;
@@ -134,11 +139,23 @@ export interface CreateApplicationCredentialInput {
     environment: ApplicationEnvironment;
     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';
 /** Aggregate totals for an application over the requested period. */
@@ -245,11 +262,13 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
         createApplicationCredential(applicationId: string, data: CreateApplicationCredentialInput): Promise<ApplicationCredentialWithSecret>;
         /**
          * 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`.
          */
-        rotateApplicationCredential(applicationId: string, credentialId: string): Promise<ApplicationCredentialWithSecret>;
+        rotateApplicationCredential(applicationId: string, credentialId: string): Promise<RotateApplicationCredentialResult>;
         /**
          * Revoke a credential (`status='revoked'`). Revoked credentials can no
          * longer authenticate.
@@ -310,7 +329,12 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
         healthCheck(): Promise<{
             status: string;
             users?: number;
-            timestamp?: string;
+            timestamp? /**
+             * Create a credential. The plaintext `secret` is returned exactly ONCE;
+             * the server stores only a hash and will never return it again.
+             * @param applicationId - The application's Mongo `_id`.
+             * @param data - Credential configuration.
+             */: string;
             [key: string]: any;
         }>;
     };

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -34,6 +34,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;
 }
 /**
  * Options for oxyClient.auth() middleware

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -83,6 +83,7 @@ export type {
     TransferApplicationOwnershipInput,
     CreateApplicationCredentialInput,
     ApplicationCredentialWithSecret,
+    RotateApplicationCredentialResult,
     ApplicationUsagePeriod,
     ApplicationUsageSummary,
     ApplicationUsageByDay,

package/src/mixins/OxyServices.applications.ts

@@ -100,6 +100,11 @@ 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;
@@ -152,12 +157,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';
 
@@ -445,16 +463,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) {