@serve.zone/interfaces 17.5.0 → 18.1.0

package/changelog.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026-07-23 - 18.1.0
+
+### Features
+
+- add host-neutral platform OIDC and app-scoped role contracts for hosted apps
+  - Declare App Store OIDC capabilities without enabling them automatically.
+  - Bind client identity, token audience, and role assignments to an immutable app instance.
+  - Validate canonical same-origin callbacks, secret environment mappings, registrations, and audience-scoped claims.
+  - Document the shared per-instance enablement contract for Onebox and Cloudly.
+
+## 2026-07-23 - 18.0.0
+
+### Breaking Changes
+
+- require durable controller mutation fences for Web Push binding synchronization and exact-owner deletion
+- replace ID-only Web Push deletion requests with owner-scoped, fenced deletion requests
+
 ## 2026-07-23 - 17.5.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/appstore/types.d.ts

@@ -1,4 +1,5 @@
 import type { IServiceSecretFile } from '../data/service.js';
+import { type IHostedAppRoleDefinition } from '../data/hostedapp.js';
 import type { IServiceDomainRoute, IServicePublicPortMapping, IServiceTargetPort } from '../data/serviceports.js';
 import type { IStorageCapacityRequest, IStorageClassRequirement, TFilesystemStorageAccessMode, TObjectStorageAccessMode, TObjectStorageDelivery, TStorageReclaimPolicy, TStorageResourceKind, TStorageSnapshotMode } from '../platform/storage.js';
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
@@ -132,6 +133,23 @@ export interface IAppStorePublishedPort {
     protocol?: 'tcp' | 'udp';
     hostIp?: string;
 }
+export interface IAppStorePlatformOidcEnvironmentVariables {
+    issuerUrl: string;
+    clientId: string;
+    /** The hosting platform must deliver this value through its secret environment path. */
+    clientSecret: string;
+    redirectUri: string;
+    audience: string;
+}
+export interface IAppStorePlatformOidcCapability {
+    /** Callback path relative to the app's canonical HTTPS origin. */
+    redirectPath: string;
+    roles: IHostedAppRoleDefinition[];
+    environmentVariables: IAppStorePlatformOidcEnvironmentVariables;
+    clientAuthenticationMethod: 'client_secret_basic' | 'client_secret_post';
+}
+export declare const validateAppStorePlatformOidcCapability: (capabilityArg: unknown) => string[];
+export declare const validateAppStoreVersionPlatformOidc: (configArg: unknown) => string[];
 export interface IAppStoreApp {
     id: string;
     name: string;
@@ -197,6 +215,12 @@ export interface IAppStoreVersionConfig {
     storageRequests?: TAppStoreStorageRequest[];
     publishedPorts?: IAppStorePublishedPort[];
     platformRequirements?: IAppStorePlatformRequirements;
+    /**
+     * Declares that this workload can consume platform-managed OIDC. The host
+     * still requires an explicit per-instance administrator toggle before it
+     * creates a client, injects credentials, or emits app-scoped role claims.
+     */
+    platformOidc?: IAppStorePlatformOidcCapability;
     minOneboxVersion?: string;
     minCloudlyVersion?: string;
     appStoreVersion?: string;

package/dist_ts/appstore/types.js

@@ -1,7 +1,82 @@
+import { validateHostedAppRoleDefinitions, } from '../data/hostedapp.js';
 export const appStoreStorageFeatureIds = {
     bindingsV1: 'storage.bindings.v1',
     filesystemV1: 'storage.filesystem.v1',
     objectStorageV1: 'storage.object-storage.v1',
     objectStorageSecretFileV1: 'storage.object-storage.secret-file.v1',
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9hcHBzdG9yZS90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFpQ0EsTUFBTSxDQUFDLE1BQU0seUJBQXlCLEdBQUc7SUFDdkMsVUFBVSxFQUFFLHFCQUFxQjtJQUNqQyxZQUFZLEVBQUUsdUJBQXVCO0lBQ3JDLGVBQWUsRUFBRSwyQkFBMkI7SUFDNUMseUJBQXlCLEVBQUUsdUNBQXVDO0NBQzFELENBQUMifQ==
+const appStoreEnvKeyRegex = /^[A-Z_][A-Z0-9_]*$/;
+export const validateAppStorePlatformOidcCapability = (capabilityArg) => {
+    if (capabilityArg === undefined)
+        return [];
+    if (!capabilityArg || typeof capabilityArg !== 'object' || Array.isArray(capabilityArg)) {
+        return ['platformOidc must be an object'];
+    }
+    const capability = capabilityArg;
+    const errors = [];
+    if (typeof capability.redirectPath !== 'string'
+        || !capability.redirectPath.startsWith('/')
+        || capability.redirectPath.startsWith('//')
+        || /[\\?#\s]/.test(capability.redirectPath)
+        || /%5c/i.test(capability.redirectPath)
+        || new URL(capability.redirectPath, 'https://app.invalid').pathname !== capability.redirectPath) {
+        errors.push('platformOidc.redirectPath must be a canonical same-origin path without query or fragment');
+    }
+    errors.push(...validateHostedAppRoleDefinitions(capability.roles)
+        .map((errorArg) => `platformOidc.${errorArg}`));
+    const environment = capability.environmentVariables;
+    if (!environment || typeof environment !== 'object' || Array.isArray(environment)) {
+        errors.push('platformOidc.environmentVariables must be an object');
+    }
+    else {
+        const keys = ['issuerUrl', 'clientId', 'clientSecret', 'redirectUri', 'audience'];
+        const values = keys.map((keyArg) => environment[keyArg]);
+        keys.forEach((keyArg, indexArg) => {
+            if (typeof values[indexArg] !== 'string'
+                || !appStoreEnvKeyRegex.test(values[indexArg])) {
+                errors.push(`platformOidc.environmentVariables.${keyArg} must be a valid environment key`);
+            }
+        });
+        if (new Set(values).size !== values.length) {
+            errors.push('platformOidc environment keys must be unique');
+        }
+    }
+    if (capability.clientAuthenticationMethod !== 'client_secret_basic'
+        && capability.clientAuthenticationMethod !== 'client_secret_post') {
+        errors.push('platformOidc.clientAuthenticationMethod is unsupported');
+    }
+    return errors;
+};
+export const validateAppStoreVersionPlatformOidc = (configArg) => {
+    if (!configArg || typeof configArg !== 'object' || Array.isArray(configArg)) {
+        return ['appstore config must be an object'];
+    }
+    const config = configArg;
+    const errors = validateAppStorePlatformOidcCapability(config.platformOidc);
+    if (!config.platformOidc || typeof config.platformOidc !== 'object'
+        || Array.isArray(config.platformOidc))
+        return errors;
+    const capability = config.platformOidc;
+    if (!capability.environmentVariables || typeof capability.environmentVariables !== 'object'
+        || Array.isArray(capability.environmentVariables))
+        return errors;
+    const oidcKeys = new Set(Object.values(capability.environmentVariables)
+        .filter((valueArg) => typeof valueArg === 'string'));
+    const ordinaryEnvKeys = Array.isArray(config.envVars)
+        ? config.envVars.map((envArg) => (envArg && typeof envArg === 'object' && !Array.isArray(envArg)
+            ? envArg.key
+            : undefined)).filter((valueArg) => typeof valueArg === 'string')
+        : [];
+    const secretFileKeys = Array.isArray(config.secretFiles)
+        ? config.secretFiles.map((fileArg) => (fileArg && typeof fileArg === 'object' && !Array.isArray(fileArg)
+            ? fileArg.sourceKey
+            : undefined)).filter((valueArg) => typeof valueArg === 'string')
+        : [];
+    for (const key of [...ordinaryEnvKeys, ...secretFileKeys]) {
+        if (oidcKeys.has(key)) {
+            errors.push(`platformOidc environment key '${key}' collides with app runtime input`);
+        }
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9hcHBzdG9yZS90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQ0wsZ0NBQWdDLEdBRWpDLE1BQU0sc0JBQXNCLENBQUM7QUFpQzlCLE1BQU0sQ0FBQyxNQUFNLHlCQUF5QixHQUFHO0lBQ3ZDLFVBQVUsRUFBRSxxQkFBcUI7SUFDakMsWUFBWSxFQUFFLHVCQUF1QjtJQUNyQyxlQUFlLEVBQUUsMkJBQTJCO0lBQzVDLHlCQUF5QixFQUFFLHVDQUF1QztDQUMxRCxDQUFDO0FBK0pYLE1BQU0sbUJBQW1CLEdBQUcsb0JBQW9CLENBQUM7QUFFakQsTUFBTSxDQUFDLE1BQU0sc0NBQXNDLEdBQUcsQ0FDcEQsYUFBc0IsRUFDWixFQUFFO0lBQ1osSUFBSSxhQUFhLEtBQUssU0FBUztRQUFFLE9BQU8sRUFBRSxDQUFDO0lBQzNDLElBQUksQ0FBQyxhQUFhLElBQUksT0FBTyxhQUFhLEtBQUssUUFBUSxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsYUFBYSxDQUFDLEVBQUUsQ0FBQztRQUN4RixPQUFPLENBQUMsZ0NBQWdDLENBQUMsQ0FBQztJQUM1QyxDQUFDO0lBQ0QsTUFBTSxVQUFVLEdBQUcsYUFBd0MsQ0FBQztJQUM1RCxNQUFNLE1BQU0sR0FBYSxFQUFFLENBQUM7SUFDNUIsSUFBSSxPQUFPLFVBQVUsQ0FBQyxZQUFZLEtBQUssUUFBUTtXQUMxQyxDQUFDLFVBQVUsQ0FBQyxZQUFZLENBQUMsVUFBVSxDQUFDLEdBQUcsQ0FBQztXQUN4QyxVQUFVLENBQUMsWUFBWSxDQUFDLFVBQVUsQ0FBQyxJQUFJLENBQUM7V0FDeEMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsWUFBWSxDQUFDO1dBQ3hDLE1BQU0sQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLFlBQVksQ0FBQztXQUNwQyxJQUFJLEdBQUcsQ0FBQyxVQUFVLENBQUMsWUFBWSxFQUFFLHFC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

package/dist_ts/data/hostedapp.d.ts

@@ -1,4 +1,75 @@
 export type THostedAppHostType = 'onebox' | 'cloudly' | string;
+export declare const hostedAppOidcRoleClaim: "roles";
+export declare const hostedAppOidcAppInstanceIdClaim: "servezone_app_instance_id";
+export interface IHostedAppRoleDefinition {
+    /** Stable role identifier emitted in the hosted app's audience-scoped token. */
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface IHostedAppRoleAssignment {
+    /** Immutable hosted app instance identifier. Never use a mutable service name as this boundary. */
+    appInstanceId: string;
+    userId: string;
+    roleIds: string[];
+    assignedAt: number;
+    assignedByUserId: string;
+}
+export interface IHostedAppPlatformOidcClaims {
+    iss: string;
+    sub: string;
+    /** Mutable display name only. Never use this claim as identity authority. */
+    preferred_username: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    auth_time: number;
+    nonce?: string;
+    [hostedAppOidcAppInstanceIdClaim]: string;
+    [hostedAppOidcRoleClaim]: string[];
+}
+interface IHostedAppPlatformOidcRegistrationBase {
+    /** Immutable OIDC client_id and ID-token audience for this hosted app. */
+    appInstanceId: string;
+    roleDefinitions: IHostedAppRoleDefinition[];
+    updatedAt: number;
+}
+type THostedAppRedirectUris = [string, ...string[]];
+export type IHostedAppPlatformOidcRegistration = (IHostedAppPlatformOidcRegistrationBase & {
+    status: 'disabled';
+    redirectUris: [];
+    issuer?: never;
+    clientId?: never;
+    error?: never;
+}) | (IHostedAppPlatformOidcRegistrationBase & {
+    status: 'enabling';
+    issuer: string;
+    clientId: string;
+    redirectUris: THostedAppRedirectUris;
+    error?: never;
+}) | (IHostedAppPlatformOidcRegistrationBase & {
+    status: 'enabled' | 'disabling';
+    issuer: string;
+    clientId: string;
+    redirectUris: THostedAppRedirectUris;
+    error?: never;
+}) | (IHostedAppPlatformOidcRegistrationBase & {
+    status: 'error';
+    redirectUris: string[];
+    issuer?: string;
+    clientId?: string;
+    error: string;
+});
+export declare const validateHostedAppRoleDefinitions: (rolesArg: unknown) => string[];
+export declare const validateHostedAppPlatformOidcClaims: (claimsArg: unknown, expectedArg: {
+    issuer: string;
+    appInstanceId: string;
+    nonce?: string;
+    nowEpochSeconds?: number;
+}) => string[];
+export declare const validateHostedAppPlatformOidcRegistration: (registrationArg: unknown, expectedArg: {
+    appOrigin: string;
+}) => string[];
 export type THostedAppRuntimeStatus = 'starting' | 'running' | 'setupRequired' | 'degraded' | 'stopped' | 'unknown';
 export type THostedAppBootstrapActionType = 'setupLink' | 'credentials' | 'message';
 export type THostedAppBootstrapActionStatus = 'requested' | 'ready' | 'completed' | 'dismissed' | 'expired';
@@ -55,3 +126,4 @@ export interface IHostedAppLifecycleState extends IHostedAppLifecycleReport {
 export type IHostedAppBootstrapActionRequest = Omit<IHostedAppBootstrapAction, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'completedAt' | 'dismissedAt'> & {
     id?: string;
 };
+export {};

package/dist_ts/data/hostedapp.js

@@ -1,2 +1,191 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaG9zdGVkYXBwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ob3N0ZWRhcHAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9
+export const hostedAppOidcRoleClaim = 'roles';
+export const hostedAppOidcAppInstanceIdClaim = 'servezone_app_instance_id';
+const hostedAppRoleIdRegex = /^[a-z][a-z0-9:_-]{0,63}$/;
+const hostedAppOpaqueIdRegex = /^[^\s\u0000-\u001f\u007f]{1,200}$/;
+export const validateHostedAppRoleDefinitions = (rolesArg) => {
+    if (!Array.isArray(rolesArg) || rolesArg.length < 1 || rolesArg.length > 32) {
+        return ['roles must contain between 1 and 32 role definitions'];
+    }
+    const errors = [];
+    const roleIds = new Set();
+    rolesArg.forEach((roleArg, indexArg) => {
+        if (!roleArg || typeof roleArg !== 'object' || Array.isArray(roleArg)) {
+            errors.push(`role ${indexArg + 1} must be an object`);
+            return;
+        }
+        const role = roleArg;
+        if (typeof role.id !== 'string' || !hostedAppRoleIdRegex.test(role.id)) {
+            errors.push(`role ${indexArg + 1} id must be a stable lowercase identifier`);
+        }
+        else if (roleIds.has(role.id)) {
+            errors.push(`role id '${role.id}' is duplicated`);
+        }
+        else {
+            roleIds.add(role.id);
+        }
+        if (typeof role.label !== 'string' || role.label.trim().length < 1 || role.label.length > 120) {
+            errors.push(`role ${indexArg + 1} label must contain between 1 and 120 characters`);
+        }
+        if (role.description !== undefined
+            && (typeof role.description !== 'string' || role.description.length > 500)) {
+            errors.push(`role ${indexArg + 1} description must contain at most 500 characters`);
+        }
+    });
+    return errors;
+};
+export const validateHostedAppPlatformOidcClaims = (claimsArg, expectedArg) => {
+    if (!claimsArg || typeof claimsArg !== 'object' || Array.isArray(claimsArg)) {
+        return ['OIDC claims must be an object'];
+    }
+    const claims = claimsArg;
+    const errors = [];
+    if (claims.iss !== expectedArg.issuer)
+        errors.push('OIDC issuer does not match');
+    if (claims.aud !== expectedArg.appInstanceId)
+        errors.push('OIDC audience does not match');
+    if (claims[hostedAppOidcAppInstanceIdClaim] !== expectedArg.appInstanceId) {
+        errors.push('OIDC app instance does not match the audience');
+    }
+    if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
+        errors.push('OIDC subject is missing or malformed');
+    }
+    if (typeof claims.preferred_username !== 'string'
+        || claims.preferred_username.trim().length === 0) {
+        errors.push('OIDC preferred username is missing or malformed');
+    }
+    const now = expectedArg.nowEpochSeconds ?? Math.floor(Date.now() / 1000);
+    if (!Number.isSafeInteger(claims.iat) || claims.iat < 0) {
+        errors.push('OIDC issued-at time is missing or malformed');
+    }
+    if (!Number.isSafeInteger(claims.exp) || claims.exp <= now) {
+        errors.push('OIDC token is expired or has malformed expiry');
+    }
+    if (!Number.isSafeInteger(claims.auth_time)
+        || claims.auth_time < 0
+        || claims.auth_time > now) {
+        errors.push('OIDC authentication time is missing or malformed');
+    }
+    if (expectedArg.nonce !== undefined && claims.nonce !== expectedArg.nonce) {
+        errors.push('OIDC nonce does not match');
+    }
+    const roles = claims[hostedAppOidcRoleClaim];
+    if (!Array.isArray(roles) || roles.length < 1 || roles.length > 32) {
+        errors.push('OIDC roles must be an array with between 1 and 32 entries');
+    }
+    else if (roles.some((roleArg) => typeof roleArg !== 'string'
+        || !hostedAppRoleIdRegex.test(roleArg))
+        || new Set(roles).size !== roles.length) {
+        errors.push('OIDC roles contain malformed or duplicate identifiers');
+    }
+    return errors;
+};
+export const validateHostedAppPlatformOidcRegistration = (registrationArg, expectedArg) => {
+    if (!registrationArg || typeof registrationArg !== 'object'
+        || Array.isArray(registrationArg)) {
+        return ['OIDC registration must be an object'];
+    }
+    const registration = registrationArg;
+    const errors = [];
+    let expectedOrigin;
+    try {
+        const parsedAppOrigin = new URL(expectedArg.appOrigin);
+        if (parsedAppOrigin.protocol !== 'https:'
+            || parsedAppOrigin.username
+            || parsedAppOrigin.password
+            || parsedAppOrigin.origin !== expectedArg.appOrigin) {
+            errors.push('Expected OIDC app origin must be a canonical credential-free HTTPS origin');
+        }
+        else {
+            expectedOrigin = parsedAppOrigin.origin;
+        }
+    }
+    catch {
+        errors.push('Expected OIDC app origin must be an absolute URL origin');
+    }
+    if (typeof registration.appInstanceId !== 'string'
+        || !hostedAppOpaqueIdRegex.test(registration.appInstanceId)) {
+        errors.push('OIDC registration appInstanceId is missing or malformed');
+    }
+    const statuses = ['disabled', 'enabling', 'enabled', 'disabling', 'error'];
+    if (typeof registration.status !== 'string' || !statuses.includes(registration.status)) {
+        errors.push('OIDC registration status is unsupported');
+    }
+    errors.push(...validateHostedAppRoleDefinitions(registration.roleDefinitions)
+        .map((errorArg) => `OIDC registration ${errorArg}`));
+    if (!Number.isSafeInteger(registration.updatedAt) || registration.updatedAt < 0) {
+        errors.push('OIDC registration updatedAt is missing or malformed');
+    }
+    const redirectUris = registration.redirectUris;
+    if (!Array.isArray(redirectUris)
+        || redirectUris.length > 8
+        || redirectUris.some((uriArg) => typeof uriArg !== 'string')) {
+        errors.push('OIDC registration redirectUris are malformed');
+    }
+    else {
+        if (registration.status === 'disabled' && redirectUris.length !== 0) {
+            errors.push('Disabled OIDC registration must not retain redirect URIs');
+        }
+        if (registration.status !== 'disabled'
+            && registration.status !== 'error'
+            && redirectUris.length < 1) {
+            errors.push('Active OIDC registration requires a redirect URI');
+        }
+        if (new Set(redirectUris).size !== redirectUris.length) {
+            errors.push('OIDC registration redirect URIs must be unique');
+        }
+        for (const redirectUri of redirectUris) {
+            try {
+                const parsed = new URL(redirectUri);
+                if (parsed.protocol !== 'https:'
+                    || parsed.username
+                    || parsed.password
+                    || parsed.search
+                    || parsed.hash
+                    || parsed.toString() !== redirectUri) {
+                    errors.push('OIDC registration redirect URIs must be canonical credential-free HTTPS URLs without query or fragment');
+                }
+                if (expectedOrigin && parsed.origin !== expectedOrigin) {
+                    errors.push('OIDC registration redirect URIs must use the app origin');
+                }
+            }
+            catch {
+                errors.push('OIDC registration redirect URIs must be absolute URLs');
+            }
+        }
+    }
+    const requiresIssuer = registration.status === 'enabling'
+        || registration.status === 'enabled'
+        || registration.status === 'disabling';
+    if (requiresIssuer || registration.issuer !== undefined) {
+        try {
+            const issuer = new URL(registration.issuer);
+            if (issuer.protocol !== 'https:' || issuer.username || issuer.password
+                || issuer.search || issuer.hash) {
+                errors.push('OIDC registration issuer must be a credential-free HTTPS URL without query or fragment');
+            }
+        }
+        catch {
+            errors.push('OIDC registration issuer must be an absolute URL');
+        }
+    }
+    const requiresClientId = registration.status === 'enabling'
+        || registration.status === 'enabled'
+        || registration.status === 'disabling';
+    if (registration.status === 'disabled'
+        && (registration.issuer !== undefined || registration.clientId !== undefined)) {
+        errors.push('Disabled OIDC registration must not retain issuer or client metadata');
+    }
+    if (requiresClientId && registration.clientId !== registration.appInstanceId) {
+        errors.push('OIDC registration clientId must equal appInstanceId');
+    }
+    else if (registration.clientId !== undefined
+        && registration.clientId !== registration.appInstanceId) {
+        errors.push('OIDC registration clientId must equal appInstanceId when present');
+    }
+    if (registration.status === 'error'
+        && (typeof registration.error !== 'string' || registration.error.length < 1)) {
+        errors.push('Errored OIDC registration requires an error message');
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaG9zdGVkYXBwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ob3N0ZWRhcHAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQUcsT0FBZ0IsQ0FBQztBQUN2RCxNQUFNLENBQUMsTUFBTSwrQkFBK0IsR0FBRywyQkFBb0MsQ0FBQztBQXVFcEYsTUFBTSxvQkFBb0IsR0FBRywwQkFBMEIsQ0FBQztBQUN4RCxNQUFNLHNCQUFzQixHQUFHLG1DQUFtQyxDQUFDO0FBRW5FLE1BQU0sQ0FBQyxNQUFNLGdDQUFnQyxHQUFHLENBQzlDLFFBQWlCLEVBQ1AsRUFBRTtJQUNaLElBQUksQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLFFBQVEsQ0FBQyxNQUFNLEdBQUcsQ0FBQyxJQUFJLFFBQVEsQ0FBQyxNQUFNLEdBQUcsRUFBRSxFQUFFLENBQUM7UUFDNUUsT0FBTyxDQUFDLHNEQUFzRCxDQUFDLENBQUM7SUFDbEUsQ0FBQztJQUNELE1BQU0sTUFBTSxHQUFhLEVBQUUsQ0FBQztJQUM1QixNQUFNLE9BQU8sR0FBRyxJQUFJLEdBQUcsRUFBVSxDQUFDO0lBQ2xDLFFBQVEsQ0FBQyxPQUFPLENBQUMsQ0FBQyxPQUFPLEVBQUUsUUFBUSxFQUFFLEVBQUU7UUFDckMsSUFBSSxDQUFDLE9BQU8sSUFBSSxPQUFPLE9BQU8sS0FBSyxRQUFRLElBQUksS0FBSyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsRUFBRSxDQUFDO1lBQ3RFLE1BQU0sQ0FBQyxJQUFJLENBQUMsUUFBUSxRQUFRLEdBQUcsQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO1lBQ3RELE9BQU87UUFDVCxDQUFDO1FBQ0QsTUFBTSxJQUFJLEdBQUcsT0FBa0MsQ0FBQztRQUNoRCxJQUFJLE9BQU8sSUFBSSxDQUFDLEVBQUUsS0FBSyxRQUFRLElBQUksQ0FBQyxvQkFBb0IsQ0FBQyxJQUFJLENBQUMsSUFBSSxD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

package/dist_ts/data/webpush.d.ts

@@ -17,6 +17,21 @@ export interface IWebPushResourceOwner {
     gatewayClientId: string;
     appInstanceId: string;
 }
+export type TWebPushControllerIntent = 'enabled' | 'disabled' | 'deleted';
+/**
+ * Durable controller fence for owner-scoped Web Push mutations.
+ *
+ * `id` and `epoch` are immutable for one owner. `generation` is a positive,
+ * strictly monotonic controller sequence. Reusing a generation is permitted
+ * only for the exact same operation, intent, and canonical request payload.
+ */
+export interface IWebPushControllerMutation {
+    id: string;
+    epoch: string;
+    generation: number;
+    operationId: string;
+    intent: TWebPushControllerIntent;
+}
 /** JSON form returned by the browser Push API. */
 export interface IWebPushSubscription {
     endpoint: string;

package/dist_ts/requests/webpush.d.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
-import type { IWebPushBinding, IWebPushCredentialOneTimeSecret, IWebPushDeliveryStatus, IWebPushNotificationPayload, IWebPushResourceOwner, IWebPushServiceStatus, IWebPushSubscription, TWebPushCancellationTarget, TWebPushUrgency } from '../data/webpush.js';
+import type { IWebPushBinding, IWebPushControllerMutation, IWebPushCredentialOneTimeSecret, IWebPushDeliveryStatus, IWebPushNotificationPayload, IWebPushResourceOwner, IWebPushServiceStatus, IWebPushSubscription, TWebPushCancellationTarget, TWebPushUrgency } from '../data/webpush.js';
 /** Control-plane authentication. Never accepted by application delivery RPCs. */
 export interface IWebPushControlRequestAuth {
     identity?: IIdentity;
@@ -30,6 +30,7 @@ export interface IReq_SyncWebPushBinding extends plugins.typedrequestInterfaces.
     method: 'syncWebPushBinding';
     request: {
         auth: IWebPushControlRequestAuth;
+        controller: IWebPushControllerMutation;
         binding: TWebPushBindingSync;
     };
     response: {
@@ -43,7 +44,9 @@ export interface IReq_DeleteWebPushBinding extends plugins.typedrequestInterface
     method: 'deleteWebPushBinding';
     request: {
         auth: IWebPushControlRequestAuth;
-        id: string;
+        owner: IWebPushResourceOwner;
+        id?: string;
+        controller: IWebPushControllerMutation;
     };
     response: {
         success: boolean;

package/package.json

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

package/readme.md

@@ -208,6 +208,45 @@ if (webTarget && data.isHttpServiceTargetProtocol(webTarget.protocol)) {
 
 `normalizeServicePortData()` returns service data with canonical `targetPorts`, domain `targetPort` refs, and `publicPortMappings` while removing legacy domain `port` fields from normalized writes.
 
+## Hosted-App Authorization and Platform OIDC
+
+An App Store version can declare that it supports platform-managed OpenID Connect. This is a capability declaration only: Onebox and Cloudly keep OIDC disabled until an administrator explicitly enables it for that exact app instance, and they can disable it again without changing the template.
+
+```typescript
+import { appstore } from '@serve.zone/interfaces';
+
+const config: appstore.IAppStoreVersionConfig = {
+  image: 'registry.example.com/example/app:1.0.0',
+  platformOidc: {
+    redirectPath: '/auth/oidc/callback',
+    roles: [
+      { id: 'admin', label: 'Administrator' },
+      { id: 'user', label: 'User' },
+    ],
+    environmentVariables: {
+      issuerUrl: 'SERVEZONE_PLATFORM_OIDC_ISSUER',
+      clientId: 'SERVEZONE_PLATFORM_OIDC_CLIENT_ID',
+      clientSecret: 'SERVEZONE_PLATFORM_OIDC_CLIENT_SECRET',
+      redirectUri: 'SERVEZONE_PLATFORM_OIDC_REDIRECT_URI',
+      audience: 'SERVEZONE_PLATFORM_OIDC_AUDIENCE',
+    },
+    clientAuthenticationMethod: 'client_secret_basic',
+  },
+};
+```
+
+`redirectPath` is a canonical callback path on the app's HTTPS origin. Registration validation also requires that canonical app origin explicitly and rejects cross-origin, normalized, query-bearing, fragment-bearing, or duplicate callback URLs. The five environment values are environment-key names, not credentials embedded in the manifest. A host injects the generated client secret through its secret environment path and injects the other registration values only while OIDC is enabled.
+
+`data.IHostedAppRoleAssignment` binds a stable user subject to an immutable `appInstanceId`. That same app instance is the OIDC `client_id`, the ID-token `aud`, and the `servezone_app_instance_id` claim. Tokens include only the assigned roles for that audience; `preferred_username` is display metadata and must not be treated as identity authority.
+
+Validate untrusted manifests, registrations, and claims with:
+
+- `data.validateHostedAppRoleDefinitions`
+- `data.validateHostedAppPlatformOidcRegistration`
+- `data.validateHostedAppPlatformOidcClaims`
+- `appstore.validateAppStorePlatformOidcCapability`
+- `appstore.validateAppStoreVersionPlatformOidc`
+
 ## TypedRequest Contracts
 
 Use `requests` when registering handlers with `@api.global/typedrequest` or when creating typed requests through a TypedSocket client.

package/ts/00_commitinfo_data.ts

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

package/ts/appstore/types.ts

@@ -1,4 +1,8 @@
 import type { IServiceSecretFile } from '../data/service.js';
+import {
+  validateHostedAppRoleDefinitions,
+  type IHostedAppRoleDefinition,
+} from '../data/hostedapp.js';
 import type {
   IServiceDomainRoute,
   IServicePublicPortMapping,
@@ -178,6 +182,105 @@ export interface IAppStorePublishedPort {
   hostIp?: string;
 }
 
+export interface IAppStorePlatformOidcEnvironmentVariables {
+  issuerUrl: string;
+  clientId: string;
+  /** The hosting platform must deliver this value through its secret environment path. */
+  clientSecret: string;
+  redirectUri: string;
+  audience: string;
+}
+
+export interface IAppStorePlatformOidcCapability {
+  /** Callback path relative to the app's canonical HTTPS origin. */
+  redirectPath: string;
+  roles: IHostedAppRoleDefinition[];
+  environmentVariables: IAppStorePlatformOidcEnvironmentVariables;
+  clientAuthenticationMethod: 'client_secret_basic' | 'client_secret_post';
+}
+
+const appStoreEnvKeyRegex = /^[A-Z_][A-Z0-9_]*$/;
+
+export const validateAppStorePlatformOidcCapability = (
+  capabilityArg: unknown,
+): string[] => {
+  if (capabilityArg === undefined) return [];
+  if (!capabilityArg || typeof capabilityArg !== 'object' || Array.isArray(capabilityArg)) {
+    return ['platformOidc must be an object'];
+  }
+  const capability = capabilityArg as Record<string, unknown>;
+  const errors: string[] = [];
+  if (typeof capability.redirectPath !== 'string'
+    || !capability.redirectPath.startsWith('/')
+    || capability.redirectPath.startsWith('//')
+    || /[\\?#\s]/.test(capability.redirectPath)
+    || /%5c/i.test(capability.redirectPath)
+    || new URL(capability.redirectPath, 'https://app.invalid').pathname !== capability.redirectPath) {
+    errors.push('platformOidc.redirectPath must be a canonical same-origin path without query or fragment');
+  }
+  errors.push(...validateHostedAppRoleDefinitions(capability.roles)
+    .map((errorArg) => `platformOidc.${errorArg}`));
+
+  const environment = capability.environmentVariables;
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)) {
+    errors.push('platformOidc.environmentVariables must be an object');
+  } else {
+    const keys = ['issuerUrl', 'clientId', 'clientSecret', 'redirectUri', 'audience'] as const;
+    const values = keys.map((keyArg) => (environment as Record<string, unknown>)[keyArg]);
+    keys.forEach((keyArg, indexArg) => {
+      if (typeof values[indexArg] !== 'string'
+        || !appStoreEnvKeyRegex.test(values[indexArg] as string)) {
+        errors.push(`platformOidc.environmentVariables.${keyArg} must be a valid environment key`);
+      }
+    });
+    if (new Set(values).size !== values.length) {
+      errors.push('platformOidc environment keys must be unique');
+    }
+  }
+  if (capability.clientAuthenticationMethod !== 'client_secret_basic'
+    && capability.clientAuthenticationMethod !== 'client_secret_post') {
+    errors.push('platformOidc.clientAuthenticationMethod is unsupported');
+  }
+  return errors;
+};
+
+export const validateAppStoreVersionPlatformOidc = (
+  configArg: unknown,
+): string[] => {
+  if (!configArg || typeof configArg !== 'object' || Array.isArray(configArg)) {
+    return ['appstore config must be an object'];
+  }
+  const config = configArg as Record<string, unknown>;
+  const errors = validateAppStorePlatformOidcCapability(config.platformOidc);
+  if (!config.platformOidc || typeof config.platformOidc !== 'object'
+    || Array.isArray(config.platformOidc)) return errors;
+  const capability = config.platformOidc as Record<string, unknown>;
+  if (!capability.environmentVariables || typeof capability.environmentVariables !== 'object'
+    || Array.isArray(capability.environmentVariables)) return errors;
+  const oidcKeys = new Set(Object.values(capability.environmentVariables)
+    .filter((valueArg): valueArg is string => typeof valueArg === 'string'));
+  const ordinaryEnvKeys = Array.isArray(config.envVars)
+    ? config.envVars.map((envArg) => (
+        envArg && typeof envArg === 'object' && !Array.isArray(envArg)
+          ? (envArg as Record<string, unknown>).key
+          : undefined
+      )).filter((valueArg): valueArg is string => typeof valueArg === 'string')
+    : [];
+  const secretFileKeys = Array.isArray(config.secretFiles)
+    ? config.secretFiles.map((fileArg) => (
+        fileArg && typeof fileArg === 'object' && !Array.isArray(fileArg)
+          ? (fileArg as Record<string, unknown>).sourceKey
+          : undefined
+      )).filter((valueArg): valueArg is string => typeof valueArg === 'string')
+    : [];
+  for (const key of [...ordinaryEnvKeys, ...secretFileKeys]) {
+    if (oidcKeys.has(key)) {
+      errors.push(`platformOidc environment key '${key}' collides with app runtime input`);
+    }
+  }
+  return errors;
+};
+
 export interface IAppStoreApp {
   id: string;
   name: string;
@@ -246,6 +349,12 @@ export interface IAppStoreVersionConfig {
   storageRequests?: TAppStoreStorageRequest[];
   publishedPorts?: IAppStorePublishedPort[];
   platformRequirements?: IAppStorePlatformRequirements;
+  /**
+   * Declares that this workload can consume platform-managed OIDC. The host
+   * still requires an explicit per-instance administrator toggle before it
+   * creates a client, injects credentials, or emits app-scoped role claims.
+   */
+  platformOidc?: IAppStorePlatformOidcCapability;
   minOneboxVersion?: string;
   minCloudlyVersion?: string;
   appStoreVersion?: string;

package/ts/data/hostedapp.ts

@@ -1,5 +1,273 @@
 export type THostedAppHostType = 'onebox' | 'cloudly' | string;
 
+export const hostedAppOidcRoleClaim = 'roles' as const;
+export const hostedAppOidcAppInstanceIdClaim = 'servezone_app_instance_id' as const;
+
+export interface IHostedAppRoleDefinition {
+  /** Stable role identifier emitted in the hosted app's audience-scoped token. */
+  id: string;
+  label: string;
+  description?: string;
+}
+
+export interface IHostedAppRoleAssignment {
+  /** Immutable hosted app instance identifier. Never use a mutable service name as this boundary. */
+  appInstanceId: string;
+  userId: string;
+  roleIds: string[];
+  assignedAt: number;
+  assignedByUserId: string;
+}
+
+export interface IHostedAppPlatformOidcClaims {
+  iss: string;
+  sub: string;
+  /** Mutable display name only. Never use this claim as identity authority. */
+  preferred_username: string;
+  aud: string;
+  iat: number;
+  exp: number;
+  auth_time: number;
+  nonce?: string;
+  [hostedAppOidcAppInstanceIdClaim]: string;
+  [hostedAppOidcRoleClaim]: string[];
+}
+
+interface IHostedAppPlatformOidcRegistrationBase {
+  /** Immutable OIDC client_id and ID-token audience for this hosted app. */
+  appInstanceId: string;
+  roleDefinitions: IHostedAppRoleDefinition[];
+  updatedAt: number;
+}
+
+type THostedAppRedirectUris = [string, ...string[]];
+
+export type IHostedAppPlatformOidcRegistration =
+  | (IHostedAppPlatformOidcRegistrationBase & {
+      status: 'disabled';
+      redirectUris: [];
+      issuer?: never;
+      clientId?: never;
+      error?: never;
+    })
+  | (IHostedAppPlatformOidcRegistrationBase & {
+      status: 'enabling';
+      issuer: string;
+      clientId: string;
+      redirectUris: THostedAppRedirectUris;
+      error?: never;
+    })
+  | (IHostedAppPlatformOidcRegistrationBase & {
+      status: 'enabled' | 'disabling';
+      issuer: string;
+      clientId: string;
+      redirectUris: THostedAppRedirectUris;
+      error?: never;
+    })
+  | (IHostedAppPlatformOidcRegistrationBase & {
+      status: 'error';
+      redirectUris: string[];
+      issuer?: string;
+      clientId?: string;
+      error: string;
+    });
+
+const hostedAppRoleIdRegex = /^[a-z][a-z0-9:_-]{0,63}$/;
+const hostedAppOpaqueIdRegex = /^[^\s\u0000-\u001f\u007f]{1,200}$/;
+
+export const validateHostedAppRoleDefinitions = (
+  rolesArg: unknown,
+): string[] => {
+  if (!Array.isArray(rolesArg) || rolesArg.length < 1 || rolesArg.length > 32) {
+    return ['roles must contain between 1 and 32 role definitions'];
+  }
+  const errors: string[] = [];
+  const roleIds = new Set<string>();
+  rolesArg.forEach((roleArg, indexArg) => {
+    if (!roleArg || typeof roleArg !== 'object' || Array.isArray(roleArg)) {
+      errors.push(`role ${indexArg + 1} must be an object`);
+      return;
+    }
+    const role = roleArg as Record<string, unknown>;
+    if (typeof role.id !== 'string' || !hostedAppRoleIdRegex.test(role.id)) {
+      errors.push(`role ${indexArg + 1} id must be a stable lowercase identifier`);
+    } else if (roleIds.has(role.id)) {
+      errors.push(`role id '${role.id}' is duplicated`);
+    } else {
+      roleIds.add(role.id);
+    }
+    if (typeof role.label !== 'string' || role.label.trim().length < 1 || role.label.length > 120) {
+      errors.push(`role ${indexArg + 1} label must contain between 1 and 120 characters`);
+    }
+    if (role.description !== undefined
+      && (typeof role.description !== 'string' || role.description.length > 500)) {
+      errors.push(`role ${indexArg + 1} description must contain at most 500 characters`);
+    }
+  });
+  return errors;
+};
+
+export const validateHostedAppPlatformOidcClaims = (
+  claimsArg: unknown,
+  expectedArg: {
+    issuer: string;
+    appInstanceId: string;
+    nonce?: string;
+    nowEpochSeconds?: number;
+  },
+): string[] => {
+  if (!claimsArg || typeof claimsArg !== 'object' || Array.isArray(claimsArg)) {
+    return ['OIDC claims must be an object'];
+  }
+  const claims = claimsArg as Record<string, unknown>;
+  const errors: string[] = [];
+  if (claims.iss !== expectedArg.issuer) errors.push('OIDC issuer does not match');
+  if (claims.aud !== expectedArg.appInstanceId) errors.push('OIDC audience does not match');
+  if (claims[hostedAppOidcAppInstanceIdClaim] !== expectedArg.appInstanceId) {
+    errors.push('OIDC app instance does not match the audience');
+  }
+  if (typeof claims.sub !== 'string' || claims.sub.length === 0) {
+    errors.push('OIDC subject is missing or malformed');
+  }
+  if (typeof claims.preferred_username !== 'string'
+    || claims.preferred_username.trim().length === 0) {
+    errors.push('OIDC preferred username is missing or malformed');
+  }
+  const now = expectedArg.nowEpochSeconds ?? Math.floor(Date.now() / 1000);
+  if (!Number.isSafeInteger(claims.iat) || (claims.iat as number) < 0) {
+    errors.push('OIDC issued-at time is missing or malformed');
+  }
+  if (!Number.isSafeInteger(claims.exp) || (claims.exp as number) <= now) {
+    errors.push('OIDC token is expired or has malformed expiry');
+  }
+  if (!Number.isSafeInteger(claims.auth_time)
+    || (claims.auth_time as number) < 0
+    || (claims.auth_time as number) > now) {
+    errors.push('OIDC authentication time is missing or malformed');
+  }
+  if (expectedArg.nonce !== undefined && claims.nonce !== expectedArg.nonce) {
+    errors.push('OIDC nonce does not match');
+  }
+  const roles = claims[hostedAppOidcRoleClaim];
+  if (!Array.isArray(roles) || roles.length < 1 || roles.length > 32) {
+    errors.push('OIDC roles must be an array with between 1 and 32 entries');
+  } else if (roles.some((roleArg) => typeof roleArg !== 'string'
+    || !hostedAppRoleIdRegex.test(roleArg))
+    || new Set(roles).size !== roles.length) {
+    errors.push('OIDC roles contain malformed or duplicate identifiers');
+  }
+  return errors;
+};
+
+export const validateHostedAppPlatformOidcRegistration = (
+  registrationArg: unknown,
+  expectedArg: { appOrigin: string },
+): string[] => {
+  if (!registrationArg || typeof registrationArg !== 'object'
+    || Array.isArray(registrationArg)) {
+    return ['OIDC registration must be an object'];
+  }
+  const registration = registrationArg as Record<string, unknown>;
+  const errors: string[] = [];
+  let expectedOrigin: string | undefined;
+  try {
+    const parsedAppOrigin = new URL(expectedArg.appOrigin);
+    if (parsedAppOrigin.protocol !== 'https:'
+      || parsedAppOrigin.username
+      || parsedAppOrigin.password
+      || parsedAppOrigin.origin !== expectedArg.appOrigin) {
+      errors.push('Expected OIDC app origin must be a canonical credential-free HTTPS origin');
+    } else {
+      expectedOrigin = parsedAppOrigin.origin;
+    }
+  } catch {
+    errors.push('Expected OIDC app origin must be an absolute URL origin');
+  }
+  if (typeof registration.appInstanceId !== 'string'
+    || !hostedAppOpaqueIdRegex.test(registration.appInstanceId)) {
+    errors.push('OIDC registration appInstanceId is missing or malformed');
+  }
+  const statuses = ['disabled', 'enabling', 'enabled', 'disabling', 'error'];
+  if (typeof registration.status !== 'string' || !statuses.includes(registration.status)) {
+    errors.push('OIDC registration status is unsupported');
+  }
+  errors.push(...validateHostedAppRoleDefinitions(registration.roleDefinitions)
+    .map((errorArg) => `OIDC registration ${errorArg}`));
+  if (!Number.isSafeInteger(registration.updatedAt) || (registration.updatedAt as number) < 0) {
+    errors.push('OIDC registration updatedAt is missing or malformed');
+  }
+
+  const redirectUris = registration.redirectUris;
+  if (!Array.isArray(redirectUris)
+    || redirectUris.length > 8
+    || redirectUris.some((uriArg) => typeof uriArg !== 'string')) {
+    errors.push('OIDC registration redirectUris are malformed');
+  } else {
+    if (registration.status === 'disabled' && redirectUris.length !== 0) {
+      errors.push('Disabled OIDC registration must not retain redirect URIs');
+    }
+    if (registration.status !== 'disabled'
+      && registration.status !== 'error'
+      && redirectUris.length < 1) {
+      errors.push('Active OIDC registration requires a redirect URI');
+    }
+    if (new Set(redirectUris).size !== redirectUris.length) {
+      errors.push('OIDC registration redirect URIs must be unique');
+    }
+    for (const redirectUri of redirectUris) {
+      try {
+        const parsed = new URL(redirectUri);
+        if (parsed.protocol !== 'https:'
+          || parsed.username
+          || parsed.password
+          || parsed.search
+          || parsed.hash
+          || parsed.toString() !== redirectUri) {
+          errors.push('OIDC registration redirect URIs must be canonical credential-free HTTPS URLs without query or fragment');
+        }
+        if (expectedOrigin && parsed.origin !== expectedOrigin) {
+          errors.push('OIDC registration redirect URIs must use the app origin');
+        }
+      } catch {
+        errors.push('OIDC registration redirect URIs must be absolute URLs');
+      }
+    }
+  }
+
+  const requiresIssuer = registration.status === 'enabling'
+    || registration.status === 'enabled'
+    || registration.status === 'disabling';
+  if (requiresIssuer || registration.issuer !== undefined) {
+    try {
+      const issuer = new URL(registration.issuer as string);
+      if (issuer.protocol !== 'https:' || issuer.username || issuer.password
+        || issuer.search || issuer.hash) {
+        errors.push('OIDC registration issuer must be a credential-free HTTPS URL without query or fragment');
+      }
+    } catch {
+      errors.push('OIDC registration issuer must be an absolute URL');
+    }
+  }
+  const requiresClientId = registration.status === 'enabling'
+    || registration.status === 'enabled'
+    || registration.status === 'disabling';
+  if (registration.status === 'disabled'
+    && (registration.issuer !== undefined || registration.clientId !== undefined)) {
+    errors.push('Disabled OIDC registration must not retain issuer or client metadata');
+  }
+  if (requiresClientId && registration.clientId !== registration.appInstanceId) {
+    errors.push('OIDC registration clientId must equal appInstanceId');
+  } else if (registration.clientId !== undefined
+    && registration.clientId !== registration.appInstanceId) {
+    errors.push('OIDC registration clientId must equal appInstanceId when present');
+  }
+  if (registration.status === 'error'
+    && (typeof registration.error !== 'string' || registration.error.length < 1)) {
+    errors.push('Errored OIDC registration requires an error message');
+  }
+  return errors;
+};
+
 export type THostedAppRuntimeStatus =
   | 'starting'
   | 'running'

package/ts/data/webpush.ts

@@ -33,6 +33,23 @@ export interface IWebPushResourceOwner {
   appInstanceId: string;
 }
 
+export type TWebPushControllerIntent = 'enabled' | 'disabled' | 'deleted';
+
+/**
+ * Durable controller fence for owner-scoped Web Push mutations.
+ *
+ * `id` and `epoch` are immutable for one owner. `generation` is a positive,
+ * strictly monotonic controller sequence. Reusing a generation is permitted
+ * only for the exact same operation, intent, and canonical request payload.
+ */
+export interface IWebPushControllerMutation {
+  id: string;
+  epoch: string;
+  generation: number;
+  operationId: string;
+  intent: TWebPushControllerIntent;
+}
+
 /** JSON form returned by the browser Push API. */
 export interface IWebPushSubscription {
   endpoint: string;

package/ts/requests/webpush.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
 import type {
   IWebPushBinding,
+  IWebPushControllerMutation,
   IWebPushCredentialOneTimeSecret,
   IWebPushDeliveryStatus,
   IWebPushNotificationPayload,
@@ -54,6 +55,7 @@ export interface IReq_SyncWebPushBinding extends plugins.typedrequestInterfaces.
   method: 'syncWebPushBinding';
   request: {
     auth: IWebPushControlRequestAuth;
+    controller: IWebPushControllerMutation;
     binding: TWebPushBindingSync;
   };
   response: {
@@ -71,7 +73,9 @@ export interface IReq_DeleteWebPushBinding extends plugins.typedrequestInterface
   method: 'deleteWebPushBinding';
   request: {
     auth: IWebPushControlRequestAuth;
-    id: string;
+    owner: IWebPushResourceOwner;
+    id?: string;
+    controller: IWebPushControllerMutation;
   };
   response: {
     success: boolean;