@serve.zone/interfaces 30.1.0 → 30.2.0

package/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-09-09 - 30.2.0
+
+### Features
+
+- add service machine credential contracts (service-credentials)
+  - Add service machine credential grant, metadata and mutation contracts with structural snapshot validators.
+  - Expose admin typed requests for inspecting metadata and creating, rotating or revoking service machine credentials.
+  - Document SecretSet delivery semantics and add validation coverage for credential contract boundaries.
+
 ## 2026-09-09 - 30.1.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/index.d.ts

@@ -34,6 +34,7 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './servicecredential.js';
 export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';

package/dist_ts/data/index.js

@@ -34,6 +34,7 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './servicecredential.js';
 export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';
@@ -41,4 +42,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxjQUFjLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQyJ9

package/dist_ts/data/servicecredential.d.ts

@@ -0,0 +1,57 @@
+/** Workload permissions are independent of human membership and deployment grants. */
+export type TServiceMachineCapabilityV1 = 'platform:session';
+/** Exact existing-service authority. Never infer this grant from an API role. */
+export interface IServiceMachineGrantV1 {
+    organizationId: string;
+    serviceId: string;
+    capabilities: TServiceMachineCapabilityV1[];
+}
+/** Public metadata only. The bearer is delivered through the owning service's SecretSet. */
+export interface IServiceMachineCredentialMetadataV1 {
+    schemaVersion: 1;
+    credentialId: string;
+    userId: string;
+    grant: IServiceMachineGrantV1;
+    generation: number;
+    state: 'active' | 'revoked';
+    expiresAt: number;
+    createdAt: number;
+    updatedAt: number;
+    /** Exact immutable encrypted delivery version; null after revocation. */
+    delivery: {
+        secretId: string;
+        secretVersionId: string;
+    } | null;
+}
+interface IServiceMachineCredentialMutationBaseV1 {
+    schemaVersion: 1;
+    organizationId: string;
+    serviceId: string;
+    /** Retain the complete request and this ID across retries. */
+    mutationId: string;
+}
+/** Creation is absent-only; rotation and revocation require the exact current generation. */
+export type TServiceMachineCredentialMutationV1 = IServiceMachineCredentialMutationBaseV1 & ({
+    operation: 'ensure';
+    expectedGeneration: null;
+    capabilities: TServiceMachineCapabilityV1[];
+    expiresAt: number;
+} | {
+    operation: 'rotate';
+    expectedGeneration: number;
+    capabilities: TServiceMachineCapabilityV1[];
+    expiresAt: number;
+} | {
+    operation: 'revoke';
+    expectedGeneration: number;
+});
+export interface IServiceMachineCredentialMutationResultV1 {
+    /** Historical on replay; replay never restores revoked or superseded authority. */
+    credential: IServiceMachineCredentialMetadataV1;
+    replayed: boolean;
+}
+/** Structural copy only; the backend must fence live service ownership and credential authority. */
+export declare const snapshotServiceMachineGrantV1: (value: unknown) => IServiceMachineGrantV1;
+export declare const snapshotServiceMachineCredentialMutationV1: (value: unknown) => TServiceMachineCredentialMutationV1;
+export declare const snapshotServiceMachineCredentialMetadataV1: (value: unknown) => IServiceMachineCredentialMetadataV1;
+export {};

package/dist_ts/data/servicecredential.js

@@ -0,0 +1,81 @@
+const fail = () => { throw new Error('Service credential contract rejected.'); };
+function requireValue(value) { if (!value)
+    fail(); }
+const object = (value, keys) => {
+    requireValue(value !== null && typeof value === 'object' && !Array.isArray(value));
+    requireValue(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+    const actual = Reflect.ownKeys(value);
+    requireValue(actual.length === keys.length && keys.every((key) => actual.includes(key)));
+    const copy = Object.create(null);
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        requireValue(descriptor && Object.hasOwn(descriptor, 'value') && descriptor.enumerable);
+        copy[key] = descriptor.value;
+    }
+    return copy;
+};
+const identifier = (value) => {
+    requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+    return value;
+};
+const counter = (value) => {
+    requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value < Number.MAX_SAFE_INTEGER);
+    return value;
+};
+const capabilities = (value) => {
+    requireValue(Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype);
+    const keys = Reflect.ownKeys(value);
+    requireValue(keys.length === 2 && keys.includes('length') && keys.includes('0'));
+    const entry = Object.getOwnPropertyDescriptor(value, '0');
+    requireValue(entry && Object.hasOwn(entry, 'value') && entry.enumerable && entry.value === 'platform:session');
+    return ['platform:session'];
+};
+const safe = (operation) => { try {
+    return operation();
+}
+catch {
+    return fail();
+} };
+/** Structural copy only; the backend must fence live service ownership and credential authority. */
+export const snapshotServiceMachineGrantV1 = (value) => safe(() => {
+    const grant = object(value, ['organizationId', 'serviceId', 'capabilities']);
+    return { organizationId: identifier(grant.organizationId), serviceId: identifier(grant.serviceId),
+        capabilities: capabilities(grant.capabilities) };
+});
+export const snapshotServiceMachineCredentialMutationV1 = (value) => safe(() => {
+    requireValue(value !== null && typeof value === 'object');
+    const operation = Object.getOwnPropertyDescriptor(value, 'operation')?.value;
+    requireValue(operation === 'ensure' || operation === 'rotate' || operation === 'revoke');
+    const request = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'mutationId', 'operation',
+        'expectedGeneration', ...(operation === 'revoke' ? [] : ['capabilities', 'expiresAt'])]);
+    requireValue(request.schemaVersion === 1);
+    const base = { schemaVersion: 1, organizationId: identifier(request.organizationId),
+        serviceId: identifier(request.serviceId), mutationId: identifier(request.mutationId) };
+    if (operation === 'revoke')
+        return { ...base, operation, expectedGeneration: counter(request.expectedGeneration) };
+    const material = { capabilities: capabilities(request.capabilities), expiresAt: counter(request.expiresAt) };
+    if (operation === 'ensure') {
+        requireValue(request.expectedGeneration === null);
+        return { ...base, ...material, operation, expectedGeneration: null };
+    }
+    return { ...base, ...material, operation, expectedGeneration: counter(request.expectedGeneration) };
+});
+export const snapshotServiceMachineCredentialMetadataV1 = (value) => safe(() => {
+    const metadata = object(value, ['schemaVersion', 'credentialId', 'userId', 'grant', 'generation', 'state',
+        'expiresAt', 'createdAt', 'updatedAt', 'delivery']);
+    requireValue(metadata.schemaVersion === 1 && (metadata.state === 'active' || metadata.state === 'revoked'));
+    const createdAt = counter(metadata.createdAt);
+    const updatedAt = counter(metadata.updatedAt);
+    requireValue(updatedAt >= createdAt);
+    let delivery = null;
+    if (metadata.state === 'active') {
+        const version = object(metadata.delivery, ['secretId', 'secretVersionId']);
+        delivery = { secretId: identifier(version.secretId), secretVersionId: identifier(version.secretVersionId) };
+    }
+    else
+        requireValue(metadata.delivery === null);
+    return { schemaVersion: 1, credentialId: identifier(metadata.credentialId), userId: identifier(metadata.userId),
+        grant: snapshotServiceMachineGrantV1(metadata.grant), generation: counter(metadata.generation),
+        state: metadata.state, expiresAt: counter(metadata.expiresAt), createdAt, updatedAt, delivery };
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZWNyZWRlbnRpYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL3NlcnZpY2VjcmVkZW50aWFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXdEQSxNQUFNLElBQUksR0FBRyxHQUFVLEVBQUUsR0FBRyxNQUFNLElBQUksS0FBSyxDQUFDLHVDQUF1QyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDeEYsU0FBUyxZQUFZLENBQUMsS0FBYyxJQUFtQixJQUFJLENBQUMsS0FBSztJQUFFLElBQUksRUFBRSxDQUFDLENBQUMsQ0FBQztBQUM1RSxNQUFNLE1BQU0sR0FBRyxDQUFDLEtBQWMsRUFBRSxJQUFjLEVBQTJCLEVBQUU7SUFDekUsWUFBWSxDQUFDLEtBQUssS0FBSyxJQUFJLElBQUksT0FBTyxLQUFLLEtBQUssUUFBUSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDO0lBQ25GLFlBQVksQ0FBQyxNQUFNLENBQUMsY0FBYyxDQUFDLEtBQUssQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTLElBQUksTUFBTSxDQUFDLGNBQWMsQ0FBQyxLQUFLLENBQUMsS0FBSyxJQUFJLENBQUMsQ0FBQztJQUN6RyxNQUFNLE1BQU0sR0FBRyxPQUFPLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDO0lBQ3RDLFlBQVksQ0FBQyxNQUFNLENBQUMsTUFBTSxLQUFLLElBQUksQ0FBQyxNQUFNLElBQUksSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDLEdBQUcsRUFBRSxFQUFFLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDekYsTUFBTSxJQUFJLEdBQTRCLE1BQU0sQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLENBQUM7SUFDMUQsS0FBSyxNQUFNLEdBQUcsSUFBSSxJQUFJLEVBQUUsQ0FBQztRQUN2QixNQUFNLFVBQVUsR0FBRyxNQUFN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

package/dist_ts/requests/admin.d.ts

@@ -1,5 +1,30 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
+import type { IServiceMachineCredentialMetadataV1, IServiceMachineCredentialMutationResultV1, TServiceMachineCredentialMutationV1 } from '../data/servicecredential.js';
+export interface IReq_Admin_GetServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredentialV1> {
+    method: 'getServiceMachineCredentialV1';
+    request: {
+        identity: IIdentityCredential;
+        organizationId: string;
+        serviceId: string;
+    };
+    response: {
+        credential: IServiceMachineCredentialMetadataV1 | null;
+    };
+}
+/**
+ * The backend authorizes the exact service and mutates hashed credential authority,
+ * encrypted SecretSet delivery and the replay receipt in one fenced transaction.
+ * No bearer is returned. Existing legacy deployment/cluster credentials are separate.
+ */
+export interface IReq_Admin_MutateServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateServiceMachineCredentialV1> {
+    method: 'mutateServiceMachineCredentialV1';
+    request: {
+        identity: IIdentityCredential;
+        mutation: TServiceMachineCredentialMutationV1;
+    };
+    response: IServiceMachineCredentialMutationResultV1;
+}
 /** Backend-owned human credential metadata; never includes a password verifier. */
 export interface IHumanCredentialMetadata {
     userId: string;

package/package.json

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

package/readme.md

@@ -174,6 +174,24 @@ bounded time/concurrency, root-only directory/socket permissions and drained
 cleanup. The package supplies no listener, permission checks or persistent state.
 No bearer, generic rotation operation or database access is part of this IPC API.
 
+### Service Machine Credentials
+
+`requests.admin.getServiceMachineCredentialV1` inspects redacted metadata;
+`mutateServiceMachineCredentialV1` creates, rotates or revokes authority for one
+exact existing service and organization. `ensure` requires absent authority and
+a null expected generation. Rotation and revocation require the exact current
+generation. Retain the mutation ID and complete input for retry; a receipt replay
+returns historical metadata without restoring authority.
+
+`IServiceMachineGrantV1` currently grants only `platform:session`. This is separate
+from deployment grants, human membership and infrastructure permissions. The
+backend must authenticate each JWT against the current active credential
+generation, expiry and exact service ownership. Structural snapshot helpers do
+not perform these checks. Credential changes, encrypted service SecretSet
+delivery and the replay receipt must commit in the same authorized transaction.
+The response contains only the immutable secret/version reference; no bearer or
+hash is returned. Revocation removes current delivery from the metadata.
+
 ### Node-Bound Runtime Assignments
 
 The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,

package/ts/00_commitinfo_data.ts

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

package/ts/data/index.ts

@@ -34,6 +34,7 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './servicecredential.js';
 export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';

package/ts/data/servicecredential.ts

@@ -0,0 +1,130 @@
+/** Workload permissions are independent of human membership and deployment grants. */
+export type TServiceMachineCapabilityV1 = 'platform:session';
+
+/** Exact existing-service authority. Never infer this grant from an API role. */
+export interface IServiceMachineGrantV1 {
+  organizationId: string;
+  serviceId: string;
+  capabilities: TServiceMachineCapabilityV1[];
+}
+
+/** Public metadata only. The bearer is delivered through the owning service's SecretSet. */
+export interface IServiceMachineCredentialMetadataV1 {
+  schemaVersion: 1;
+  credentialId: string;
+  userId: string;
+  grant: IServiceMachineGrantV1;
+  generation: number;
+  state: 'active' | 'revoked';
+  expiresAt: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Exact immutable encrypted delivery version; null after revocation. */
+  delivery: { secretId: string; secretVersionId: string } | null;
+}
+
+interface IServiceMachineCredentialMutationBaseV1 {
+  schemaVersion: 1;
+  organizationId: string;
+  serviceId: string;
+  /** Retain the complete request and this ID across retries. */
+  mutationId: string;
+}
+
+/** Creation is absent-only; rotation and revocation require the exact current generation. */
+export type TServiceMachineCredentialMutationV1 = IServiceMachineCredentialMutationBaseV1 & (
+  | {
+      operation: 'ensure';
+      expectedGeneration: null;
+      capabilities: TServiceMachineCapabilityV1[];
+      expiresAt: number;
+    }
+  | {
+      operation: 'rotate';
+      expectedGeneration: number;
+      capabilities: TServiceMachineCapabilityV1[];
+      expiresAt: number;
+    }
+  | { operation: 'revoke'; expectedGeneration: number }
+);
+
+export interface IServiceMachineCredentialMutationResultV1 {
+  /** Historical on replay; replay never restores revoked or superseded authority. */
+  credential: IServiceMachineCredentialMetadataV1;
+  replayed: boolean;
+}
+
+const fail = (): never => { throw new Error('Service credential contract rejected.'); };
+function requireValue(value: unknown): asserts value { if (!value) fail(); }
+const object = (value: unknown, keys: string[]): Record<string, unknown> => {
+  requireValue(value !== null && typeof value === 'object' && !Array.isArray(value));
+  requireValue(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+  const actual = Reflect.ownKeys(value);
+  requireValue(actual.length === keys.length && keys.every((key) => actual.includes(key)));
+  const copy: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    requireValue(descriptor && Object.hasOwn(descriptor, 'value') && descriptor.enumerable);
+    copy[key] = descriptor.value;
+  }
+  return copy;
+};
+const identifier = (value: unknown): string => {
+  requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+  return value;
+};
+const counter = (value: unknown): number => {
+  requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value < Number.MAX_SAFE_INTEGER);
+  return value;
+};
+const capabilities = (value: unknown): TServiceMachineCapabilityV1[] => {
+  requireValue(Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype);
+  const keys = Reflect.ownKeys(value);
+  requireValue(keys.length === 2 && keys.includes('length') && keys.includes('0'));
+  const entry = Object.getOwnPropertyDescriptor(value, '0');
+  requireValue(entry && Object.hasOwn(entry, 'value') && entry.enumerable && entry.value === 'platform:session');
+  return ['platform:session'];
+};
+const safe = <T>(operation: () => T): T => { try { return operation(); } catch { return fail(); } };
+
+/** Structural copy only; the backend must fence live service ownership and credential authority. */
+export const snapshotServiceMachineGrantV1 = (value: unknown): IServiceMachineGrantV1 => safe(() => {
+  const grant = object(value, ['organizationId', 'serviceId', 'capabilities']);
+  return { organizationId: identifier(grant.organizationId), serviceId: identifier(grant.serviceId),
+    capabilities: capabilities(grant.capabilities) };
+});
+
+export const snapshotServiceMachineCredentialMutationV1 = (value: unknown): TServiceMachineCredentialMutationV1 => safe(() => {
+  requireValue(value !== null && typeof value === 'object');
+  const operation = Object.getOwnPropertyDescriptor(value, 'operation')?.value;
+  requireValue(operation === 'ensure' || operation === 'rotate' || operation === 'revoke');
+  const request = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'mutationId', 'operation',
+    'expectedGeneration', ...(operation === 'revoke' ? [] : ['capabilities', 'expiresAt'])]);
+  requireValue(request.schemaVersion === 1);
+  const base = { schemaVersion: 1 as const, organizationId: identifier(request.organizationId),
+    serviceId: identifier(request.serviceId), mutationId: identifier(request.mutationId) };
+  if (operation === 'revoke') return { ...base, operation, expectedGeneration: counter(request.expectedGeneration) };
+  const material = { capabilities: capabilities(request.capabilities), expiresAt: counter(request.expiresAt) };
+  if (operation === 'ensure') {
+    requireValue(request.expectedGeneration === null);
+    return { ...base, ...material, operation, expectedGeneration: null };
+  }
+  return { ...base, ...material, operation, expectedGeneration: counter(request.expectedGeneration) };
+});
+
+export const snapshotServiceMachineCredentialMetadataV1 = (value: unknown): IServiceMachineCredentialMetadataV1 => safe(() => {
+  const metadata = object(value, ['schemaVersion', 'credentialId', 'userId', 'grant', 'generation', 'state',
+    'expiresAt', 'createdAt', 'updatedAt', 'delivery']);
+  requireValue(metadata.schemaVersion === 1 && (metadata.state === 'active' || metadata.state === 'revoked'));
+  const createdAt = counter(metadata.createdAt);
+  const updatedAt = counter(metadata.updatedAt);
+  requireValue(updatedAt >= createdAt);
+  let delivery: IServiceMachineCredentialMetadataV1['delivery'] = null;
+  if (metadata.state === 'active') {
+    const version = object(metadata.delivery, ['secretId', 'secretVersionId']);
+    delivery = { secretId: identifier(version.secretId), secretVersionId: identifier(version.secretVersionId) };
+  } else requireValue(metadata.delivery === null);
+  return { schemaVersion: 1, credentialId: identifier(metadata.credentialId), userId: identifier(metadata.userId),
+    grant: snapshotServiceMachineGrantV1(metadata.grant), generation: counter(metadata.generation),
+    state: metadata.state, expiresAt: counter(metadata.expiresAt), createdAt, updatedAt, delivery };
+});

package/ts/requests/admin.ts

@@ -1,5 +1,30 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
+import type {
+  IServiceMachineCredentialMetadataV1, IServiceMachineCredentialMutationResultV1,
+  TServiceMachineCredentialMutationV1,
+} from '../data/servicecredential.js';
+
+export interface IReq_Admin_GetServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredentialV1
+> {
+  method: 'getServiceMachineCredentialV1';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { credential: IServiceMachineCredentialMetadataV1 | null };
+}
+
+/**
+ * The backend authorizes the exact service and mutates hashed credential authority,
+ * encrypted SecretSet delivery and the replay receipt in one fenced transaction.
+ * No bearer is returned. Existing legacy deployment/cluster credentials are separate.
+ */
+export interface IReq_Admin_MutateServiceMachineCredentialV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateServiceMachineCredentialV1
+> {
+  method: 'mutateServiceMachineCredentialV1';
+  request: { identity: IIdentityCredential; mutation: TServiceMachineCredentialMutationV1 };
+  response: IServiceMachineCredentialMutationResultV1;
+}
 
 /** Backend-owned human credential metadata; never includes a password verifier. */
 export interface IHumanCredentialMetadata {