@serve.zone/interfaces 28.2.0 → 28.3.0

package/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026-09-08 - 28.3.0
+
+### Features
+
+- add human credential administration contracts (admin)
+  - Define getHumanCredential and mutateHumanCredential TypedRequest interfaces for inspecting and mutating human credential metadata.
+  - Support password rotation, password login revocation, and session revocation operations with generation checks and replay handling.
+  - Document human credential administration behavior, session invalidation semantics, and password handling expectations.
+
+### Fixes
+
+- pin @types/node and update pnpm package manager (package)
+  - Pins @types/node at 26.4.0 instead of using a caret range.
+  - Updates packageManager from pnpm 11.25.0 to 12.2.1.
+
 ## 2026-09-06 - 28.2.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/requests/admin.d.ts

@@ -1,5 +1,49 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
+/** Backend-owned human credential metadata; never includes a password verifier. */
+export interface IHumanCredentialMetadata {
+    userId: string;
+    generation: number;
+    passwordEnabled: boolean;
+    updatedAt: number;
+}
+export interface IReq_Admin_GetHumanCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetHumanCredential> {
+    method: 'getHumanCredential';
+    request: {
+        identity: IIdentityCredential;
+        userId: string;
+    };
+    response: {
+        credential: IHumanCredentialMetadata;
+    };
+}
+/**
+ * Requires a recently authenticated human administrator. Each operation invalidates
+ * previously issued human UI/API and registry sessions. Revoking a password retains
+ * the user's upstream OIDC binding, so a new trusted OIDC login remains possible.
+ */
+export interface IReq_Admin_MutateHumanCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateHumanCredential> {
+    method: 'mutateHumanCredential';
+    request: {
+        identity: IIdentityCredential;
+        userId: string;
+        mutationId: string;
+        expectedGeneration: number;
+        operation: {
+            kind: 'rotatePassword';
+            password: string;
+        } | {
+            kind: 'revokePassword';
+        } | {
+            kind: 'revokeSessions';
+        };
+    };
+    response: {
+        /** Historical on replay; read getHumanCredential for current state. */
+        credential: IHumanCredentialMetadata;
+        replayed: boolean;
+    };
+}
 export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_LoginWithUsernameAndPassword> {
     method: 'adminLoginWithUsernameAndPassword';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "28.2.0",
+  "version": "28.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -31,7 +31,7 @@
     "@git.zone/tsdoc": "^2.2.0",
     "@git.zone/tsrun": "^2.0.6",
     "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.4.1"
+    "@types/node": "26.4.0"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -47,6 +47,21 @@ validator; unlike `@serve.zone/interfaces/runtime`, it does not load the general
 runtime graph, `plugins.js`, SmartCrypto, TypedRequest, Corestore, or settlement
 runtime modules.
 
+### Human Credential Administration
+
+`requests.admin.getHumanCredential` and `mutateHumanCredential` describe human
+credential inspection and mutation for recently authenticated administrators.
+Operations rotate a password, revoke password login, or revoke existing sessions.
+Each successful mutation advances the generation and invalidates older human
+UI/API and OCI registry sessions. Upstream OIDC identity bindings remain intact.
+
+Send the expected generation and a stable mutation ID. After a lost response,
+authenticate again and repeat the same request. A replay returns the original
+metadata without applying the operation again; inspect current metadata separately.
+Requests containing passwords must never be logged. Responses contain no passwords
+or verifiers. Cloudly owns validation, atomic persistence, and session enforcement;
+these shared contracts alone do not implement an endpoint.
+
 ### Node Credential Administration
 
 `requests.node` defines `getNodeCredential`, `rotateNodeCredential` and

package/ts/00_commitinfo_data.ts

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

package/ts/requests/admin.ts

@@ -1,6 +1,50 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
 
+/** Backend-owned human credential metadata; never includes a password verifier. */
+export interface IHumanCredentialMetadata {
+  userId: string;
+  generation: number;
+  passwordEnabled: boolean;
+  updatedAt: number;
+}
+
+export interface IReq_Admin_GetHumanCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_GetHumanCredential
+> {
+  method: 'getHumanCredential';
+  request: { identity: IIdentityCredential; userId: string };
+  response: { credential: IHumanCredentialMetadata };
+}
+
+/**
+ * Requires a recently authenticated human administrator. Each operation invalidates
+ * previously issued human UI/API and registry sessions. Revoking a password retains
+ * the user's upstream OIDC binding, so a new trusted OIDC login remains possible.
+ */
+export interface IReq_Admin_MutateHumanCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_MutateHumanCredential
+> {
+  method: 'mutateHumanCredential';
+  request: {
+    identity: IIdentityCredential;
+    userId: string;
+    mutationId: string;
+    expectedGeneration: number;
+    operation:
+      | { kind: 'rotatePassword'; password: string }
+      | { kind: 'revokePassword' }
+      | { kind: 'revokeSessions' };
+  };
+  response: {
+    /** Historical on replay; read getHumanCredential for current state. */
+    credential: IHumanCredentialMetadata;
+    replayed: boolean;
+  };
+}
+
 export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_Admin_LoginWithUsernameAndPassword