@serve.zone/interfaces 16.8.0 → 17.1.0

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-07-21 - 17.1.0
+
+### Features
+
+- expose the server-authoritative candidate, active, or manual lifecycle state in gateway-client auth contexts
+
+## 2026-07-21 - 17.0.0
+
+### Breaking Changes
+
+- make gateway-client credential handover explicitly two-phase (gateway)
+  - Provisioning now returns an unfinalized candidate credential without revoking existing credentials.
+  - Add candidate-authenticated finalization to activate credentials and revoke superseded client-bound credentials.
+  - Remove caller-selected gateway client finalization and provisioning-time revocation counts from the gateway API contract.
+
 ## 2026-07-21 - 16.8.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '16.8.0',
+    version: '17.1.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/gateway.d.ts

@@ -160,11 +160,20 @@ export interface IGatewayClientProvisioningSpec {
     capabilities: IGatewayTokenCapabilities;
     enabled?: boolean;
 }
-/** One-time credential material returned after durable token creation. */
+/**
+ * One-time credential material returned after durable token creation.
+ *
+ * Provisioning creates a candidate only. Existing client-bound credentials
+ * remain active until the candidate authenticates the explicit finalization
+ * request, preventing a lost provisioning response from locking out the
+ * gateway client.
+ */
 export interface IGatewayClientCredential {
     tokenId: string;
     tokenValue: string;
     issuedAt: number;
+    state: 'candidate';
+    finalizationRequired: true;
 }
 export type TGatewayClientProvisioningAction = 'created' | 'updated' | 'unchanged';
 /**
@@ -178,6 +187,8 @@ interface IGatewayClientContextBase {
     allowedRouteTargets: IGatewayRouteTargetAllowance[];
     capabilities: IGatewayTokenCapabilities;
 }
+/** Server-authoritative lifecycle of an authenticated gateway-client credential. */
+export type TGatewayCredentialState = 'candidate' | 'active' | 'manual';
 /**
  * Resolved authorization context. A gateway-client role always proves the
  * concrete credential, bound client, and current live policy generation.
@@ -186,6 +197,8 @@ interface IGatewayClientContextBase {
 export type IGatewayClientContext = IGatewayClientContextBase & ({
     role: 'gatewayClient';
     credentialId: string;
+    /** Present on lifecycle-aware gateways. Candidates are validation/finalization-only. */
+    credentialState?: TGatewayCredentialState;
     gatewayClient: {
         type: TGatewayClientType;
         id: string;

package/dist_ts/requests/gateway.d.ts

@@ -33,10 +33,10 @@ export interface IReq_GetGatewayClientContext extends plugins.typedrequestInterf
     };
 }
 /**
- * Admin-only idempotent gateway-client upsert and credential handover.
- * A newly created durable client-bound credential is returned once, then prior
- * credentials bound to that client are revoked. Bootstrap and admin credentials
- * are never part of that revocation set.
+ * Admin-only gateway-client upsert and candidate credential issue.
+ * Provisioning never revokes prior client-bound credentials. The returned
+ * candidate must prove possession through finalizeGatewayClientCredential
+ * before the gateway activates it and revokes superseded siblings.
  */
 export interface IReq_ProvisionGatewayClientCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ProvisionGatewayClientCredential> {
     method: 'provisionGatewayClientCredential';
@@ -52,9 +52,35 @@ export interface IReq_ProvisionGatewayClientCredential extends plugins.typedrequ
         success: true;
         action: TGatewayClientProvisioningAction;
         gatewayClient: IGatewayClient;
-        /** One-time credential material returned only after durable creation. */
+        /** One-time, unfinalized credential material returned after durable creation. */
         credential: IGatewayClientCredential;
+        message?: string;
+    } | {
+        success: false;
+        message: string;
+    };
+}
+/**
+ * Candidate-authenticated completion of a gateway-client credential handover.
+ * The gateway resolves client ownership from the candidate token itself; the
+ * caller cannot select a gateway client or finalize another credential.
+ */
+export interface IReq_FinalizeGatewayClientCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_FinalizeGatewayClientCredential> {
+    method: 'finalizeGatewayClientCredential';
+    request: {
+        /** The one-time candidate token value returned by provisioning. */
+        apiToken: string;
+        /** Must identify the same candidate credential as apiToken. */
+        tokenId: string;
+        /** Admin/operator identities cannot finalize a candidate by substitution. */
+        identity?: never;
+    };
+    response: {
+        success: true;
+        gatewayClientId: string;
+        tokenId: string;
         revokedCredentialCount: number;
+        finalizedAt: number;
         message?: string;
     } | {
         success: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "16.8.0",
+  "version": "17.1.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '16.8.0',
+  version: '17.1.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/gateway.ts

@@ -190,11 +190,20 @@ export interface IGatewayClientProvisioningSpec {
   enabled?: boolean;
 }
 
-/** One-time credential material returned after durable token creation. */
+/**
+ * One-time credential material returned after durable token creation.
+ *
+ * Provisioning creates a candidate only. Existing client-bound credentials
+ * remain active until the candidate authenticates the explicit finalization
+ * request, preventing a lost provisioning response from locking out the
+ * gateway client.
+ */
 export interface IGatewayClientCredential {
   tokenId: string;
   tokenValue: string;
   issuedAt: number;
+  state: 'candidate';
+  finalizationRequired: true;
 }
 
 export type TGatewayClientProvisioningAction = 'created' | 'updated' | 'unchanged';
@@ -211,6 +220,9 @@ interface IGatewayClientContextBase {
   capabilities: IGatewayTokenCapabilities;
 }
 
+/** Server-authoritative lifecycle of an authenticated gateway-client credential. */
+export type TGatewayCredentialState = 'candidate' | 'active' | 'manual';
+
 /**
  * Resolved authorization context. A gateway-client role always proves the
  * concrete credential, bound client, and current live policy generation.
@@ -220,6 +232,8 @@ export type IGatewayClientContext = IGatewayClientContextBase & (
   | {
       role: 'gatewayClient';
       credentialId: string;
+      /** Present on lifecycle-aware gateways. Candidates are validation/finalization-only. */
+      credentialState?: TGatewayCredentialState;
       gatewayClient: {
         type: TGatewayClientType;
         id: string;

package/ts/requests/gateway.ts

@@ -58,10 +58,10 @@ export interface IReq_GetGatewayClientContext extends plugins.typedrequestInterf
 }
 
 /**
- * Admin-only idempotent gateway-client upsert and credential handover.
- * A newly created durable client-bound credential is returned once, then prior
- * credentials bound to that client are revoked. Bootstrap and admin credentials
- * are never part of that revocation set.
+ * Admin-only gateway-client upsert and candidate credential issue.
+ * Provisioning never revokes prior client-bound credentials. The returned
+ * candidate must prove possession through finalizeGatewayClientCredential
+ * before the gateway activates it and revokes superseded siblings.
  */
 export interface IReq_ProvisionGatewayClientCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -81,9 +81,41 @@ export interface IReq_ProvisionGatewayClientCredential extends plugins.typedrequ
         success: true;
         action: TGatewayClientProvisioningAction;
         gatewayClient: IGatewayClient;
-        /** One-time credential material returned only after durable creation. */
+        /** One-time, unfinalized credential material returned after durable creation. */
         credential: IGatewayClientCredential;
+        message?: string;
+      }
+    | {
+        success: false;
+        message: string;
+      };
+}
+
+/**
+ * Candidate-authenticated completion of a gateway-client credential handover.
+ * The gateway resolves client ownership from the candidate token itself; the
+ * caller cannot select a gateway client or finalize another credential.
+ */
+export interface IReq_FinalizeGatewayClientCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_FinalizeGatewayClientCredential
+> {
+  method: 'finalizeGatewayClientCredential';
+  request: {
+    /** The one-time candidate token value returned by provisioning. */
+    apiToken: string;
+    /** Must identify the same candidate credential as apiToken. */
+    tokenId: string;
+    /** Admin/operator identities cannot finalize a candidate by substitution. */
+    identity?: never;
+  };
+  response:
+    | {
+        success: true;
+        gatewayClientId: string;
+        tokenId: string;
         revokedCredentialCount: number;
+        finalizedAt: number;
         message?: string;
       }
     | {